candle-launch-bot 0.0.0-stage → 0.1.0

package/dist/exec/fills.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Book fills from the transaction, never from a quote.
+ *  - token delta: the owner's post minus pre token balance for the mint (all of its accounts)
+ *  - quote delta: the owner's native SOL change, plus any WSOL token change, with the network fee (when the
+ *    owner paid it) and token-account rent (created or returned) separated out
+ */
+export interface Fill {
+    signature: string;
+    slot: number | null;
+    blockTimeMs: number | null;
+    /** Token raw units the owner gained (buy, > 0) or gave up (sell, < 0). */
+    tokenDeltaRaw: bigint;
+    /** Lamports the owner's SOL (native + WSOL) changed by, all-in (includes fee and rent). */
+    solDeltaLamports: bigint;
+    /** Network fee the owner paid as fee payer (0 when someone else paid). */
+    networkFeeLamports: bigint;
+    /** Lamports moved into (> 0) or back out of (< 0) the owner's token accounts for this mint: rent, not price. */
+    rentLamports: bigint;
+    /** Swap leg in lamports, net of the network fee and rent: what the trade itself cost (buy, < 0) or paid (sell, > 0). */
+    swapLamports: bigint;
+    err: unknown;
+}
+export declare class FillError extends Error {
+}
+export declare function fillFromTx(tx: any, owner: string, mint: string): Fill;

package/dist/exec/fills.js

@@ -0,0 +1,53 @@
+function keysOf(tx) {
+    const keys = (tx?.transaction?.message?.accountKeys ?? []).map((k) => (typeof k === "string" ? k : k?.pubkey));
+    const loaded = tx?.meta?.loadedAddresses;
+    if (loaded)
+        keys.push(...(loaded.writable ?? []), ...(loaded.readonly ?? []));
+    return keys;
+}
+const WSOL = "So11111111111111111111111111111111111111112";
+function tokenSum(rows, owner, mint) {
+    let s = 0n;
+    for (const r of rows ?? [])
+        if (r?.owner === owner && r?.mint === mint)
+            s += BigInt(r?.uiTokenAmount?.amount ?? "0");
+    return s;
+}
+export class FillError extends Error {
+}
+export function fillFromTx(tx, owner, mint) {
+    if (!tx?.meta)
+        throw new FillError("transaction has no meta");
+    const meta = tx.meta;
+    const keys = keysOf(tx);
+    const i = keys.indexOf(owner);
+    const pre = meta.preBalances ?? [];
+    const post = meta.postBalances ?? [];
+    const native = i >= 0 ? BigInt(post[i] ?? 0) - BigInt(pre[i] ?? 0) : 0n;
+    const wsol = tokenSum(meta.postTokenBalances, owner, WSOL) - tokenSum(meta.preTokenBalances, owner, WSOL);
+    const tokenDelta = tokenSum(meta.postTokenBalances, owner, mint) - tokenSum(meta.preTokenBalances, owner, mint);
+    const fee = i === 0 ? BigInt(meta.fee ?? 0) : 0n;
+    // Rent: lamport change of the owner's token accounts for this mint (an account opened on a buy, closed on a sell).
+    const accts = new Set();
+    for (const r of [...(meta.preTokenBalances ?? []), ...(meta.postTokenBalances ?? [])])
+        if (r?.owner === owner && r?.mint === mint)
+            accts.add(r.accountIndex);
+    let rent = 0n;
+    for (const a of accts)
+        rent += BigInt(post[a] ?? 0) - BigInt(pre[a] ?? 0);
+    // An account closed in this tx drops out of postTokenBalances but keeps its index: covered by the set above.
+    const solDelta = native + wsol;
+    // The owner's SOL went to: the swap, the fee, and rent into its token account. Add the last two back.
+    const swap = solDelta + fee + rent;
+    return {
+        signature: tx.transaction?.signatures?.[0] ?? "",
+        slot: typeof tx.slot === "number" ? tx.slot : null,
+        blockTimeMs: typeof tx.blockTime === "number" ? tx.blockTime * 1000 : null,
+        tokenDeltaRaw: tokenDelta,
+        solDeltaLamports: solDelta,
+        networkFeeLamports: fee,
+        rentLamports: rent,
+        swapLamports: swap,
+        err: meta.err ?? null,
+    };
+}

package/dist/exec/trader.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The trade rail the executor drives: Candle's linked-payer flow for a TEE wallet, step by step, so the
+ * signature can be persisted BEFORE anything is broadcast:
+ *    buildTrade (payer linked) -> signLinkedTransaction (our P-256 signer, through Candle's relay)
+ *    -> [persist signature] -> submit (Candle broadcasts and confirms)
+ * The SDK's one-shot trade() hides the signature until it has been sent, so it is not used here.
+ */
+import { CandleClient, type BuildTradeRequest, type BuildTradeResult, type ExecutedTradeResult, type SecretStore, type TradeJob } from "@candledottv/agent-sdk";
+import type { Config } from "../config.ts";
+export interface TradeRail {
+    /** Who pays: a linked TEE wallet (signed here, submitted by Candle) or the embedded wallet (Candle signs and sends inside build). */
+    readonly payer: {
+        type: "linked";
+        linkedWalletId: string;
+    } | {
+        type: "main";
+    };
+    build(req: BuildTradeRequest): Promise<BuildTradeResult>;
+    sign(unsignedTransactionBase64: string): Promise<string>;
+    submit(clientTradeId: string, signedTransactionBase64: string): Promise<ExecutedTradeResult>;
+    confirm(clientTradeId: string, signature: string): Promise<ExecutedTradeResult>;
+    /** The trade's row in Candle's idempotency ledger, or null when the write never began (JOB_NOT_FOUND). */
+    job(clientTradeId: string): Promise<TradeJob | null>;
+}
+/** base58 of a signed transaction's first signature (the fee payer's): its id on chain. */
+export declare function signatureOfSigned(signedBase64: string): string;
+/** base58 of the recent blockhash inside a signed transaction (legacy or v0 message). */
+export declare function blockhashOfSigned(signedBase64: string): string;
+/** A fetch that always carries a timeout (the SDK's own requests have none). */
+export declare function timedFetch(timeoutMs: number, base?: typeof fetch): typeof fetch;
+export type ExecFn = (binary: string, args: string[]) => Promise<{
+    status: number;
+    stdout: string;
+}>;
+/** base64 PKCS#8 DER (the CLI's single-line form) or PEM -> PEM, checked to be a P-256 private key. */
+export declare function toPem(stored: string): string;
+/**
+ * The Candle CLI's own signer storage (OS keychain, service tv.candle.cli):
+ *  - a TEE wallet bound to the API key signs with the KEY signer (`candle tee signer new --key <prefix>`): keychain
+ *    account `key_signer_<keyPrefix>_<spkiSha256>`, indexed in ~/.config/candle/config.json `keySigners.entries`
+ *    by keyPrefix and signerQuorumId;
+ *  - an imported linked wallet signs with its own wallet signer: account `wallet_signer_<linkedWalletId>`.
+ * get(linkedWalletId) returns the key signer when the wallet is the resolved TEE wallet, else the wallet signer.
+ * The stored key's public key is checked against the index's spkiSha256. Nothing secret is ever logged.
+ */
+export declare class CandleCliSignerStore implements SecretStore {
+    private exec;
+    private backend;
+    private configPath;
+    private keySigner;
+    constructor(opts?: {
+        exec?: ExecFn;
+        backend?: "security" | "secret-tool";
+        configPath?: string;
+    });
+    forTeeWallet(linkedWalletId: string, keyPrefix: string, quorumId: string | null): this;
+    private read;
+    get(walletRef: string): Promise<string | null>;
+    set(): Promise<void>;
+    delete(): Promise<void>;
+}
+export declare function makeSecretStore(cfg: Config, w: ResolvedWallet, env?: NodeJS.ProcessEnv): Promise<SecretStore>;
+export interface ResolvedWallet {
+    linkedWalletId: string;
+    privyWalletId: string;
+    keyPrefix: string;
+    privyAppId: string;
+    signerQuorumId: string | null;
+}
+/**
+ * The TEE wallet this API key may trade from (GET /api/v1/agent/wallets/trading, every page), with the key's prefix
+ * and Candle's Privy app id from the same answer. Config pins (linkedWalletId, privyWalletId, privyAppId) must match.
+ */
+export declare function resolveWallet(cfg: Config, apiKey: string, f?: typeof fetch): Promise<ResolvedWallet>;
+/**
+ * The account's embedded wallet: GET /api/v1/agent/wallets/embedded must name `wallet` as its Solana address, and the
+ * key must not be denied the wallet (embeddedWalletPermission) nor the wallet undelegated (Candle could not sign).
+ */
+export declare function resolveEmbedded(cfg: Config, apiKey: string, f?: typeof fetch): Promise<{
+    address: string;
+    permission: string | null;
+}>;
+/** payer main: buildTrade executes the trade inside the call (Candle signs and broadcasts); there is nothing to sign here. */
+export declare class EmbeddedRail implements TradeRail {
+    readonly payer: {
+        type: "main";
+    };
+    private client;
+    constructor(client: CandleClient);
+    build(req: BuildTradeRequest): any;
+    sign(): Promise<string>;
+    submit(): Promise<ExecutedTradeResult>;
+    confirm(clientTradeId: string, signature: string): any;
+    job(clientTradeId: string): Promise<any>;
+}
+export declare class SdkRail implements TradeRail {
+    readonly payer: {
+        type: "linked";
+        linkedWalletId: string;
+    };
+    private client;
+    private w;
+    constructor(client: CandleClient, wallet: ResolvedWallet);
+    build(req: BuildTradeRequest): any;
+    sign(unsignedTransactionBase64: string): Promise<any>;
+    submit(clientTradeId: string, signed: string): any;
+    confirm(clientTradeId: string, signature: string): any;
+    job(clientTradeId: string): Promise<any>;
+}

package/dist/exec/trader.js

@@ -0,0 +1,310 @@
+/**
+ * The trade rail the executor drives: Candle's linked-payer flow for a TEE wallet, step by step, so the
+ * signature can be persisted BEFORE anything is broadcast:
+ *    buildTrade (payer linked) -> signLinkedTransaction (our P-256 signer, through Candle's relay)
+ *    -> [persist signature] -> submit (Candle broadcasts and confirms)
+ * The SDK's one-shot trade() hides the signature until it has been sent, so it is not used here.
+ */
+import { CandleClient, EncryptedFileSecretStore, InMemorySecretStore, } from "@candledottv/agent-sdk";
+import { spawn } from "node:child_process";
+import { createHash, createPrivateKey, createPublicKey } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { b58encode } from "../solana/base58.js";
+import { addSecret } from "../redact.js";
+/** base58 of a signed transaction's first signature (the fee payer's): its id on chain. */
+export function signatureOfSigned(signedBase64) {
+    const raw = Buffer.from(signedBase64, "base64");
+    let n = 0;
+    let shift = 0;
+    let i = 0;
+    for (; i < 3; i++) {
+        const x = raw[i];
+        n |= (x & 0x7f) << shift;
+        if (!(x & 0x80))
+            break;
+        shift += 7;
+    }
+    i++;
+    if (n < 1 || raw.length < i + 64)
+        throw new Error("signed transaction has no signature");
+    const sig = raw.subarray(i, i + 64);
+    if (sig.every((b) => b === 0))
+        throw new Error("signed transaction carries an empty signature");
+    return b58encode(sig);
+}
+/** base58 of the recent blockhash inside a signed transaction (legacy or v0 message). */
+export function blockhashOfSigned(signedBase64) {
+    const raw = Buffer.from(signedBase64, "base64");
+    const vec = (at) => {
+        let n = 0, shift = 0, i = at;
+        for (; i < at + 3; i++) {
+            n |= (raw[i] & 0x7f) << shift;
+            if (!(raw[i] & 0x80))
+                return [n, i + 1];
+            shift += 7;
+        }
+        throw new Error("bad shortvec");
+    };
+    let [nsig, at] = vec(0);
+    at += 64 * nsig;
+    if (raw[at] & 0x80)
+        at += 1; // v0 version prefix
+    at += 3; // message header
+    const [nkeys, after] = vec(at);
+    at = after + 32 * nkeys;
+    if (raw.length < at + 32)
+        throw new Error("signed transaction too short for a blockhash");
+    return b58encode(raw.subarray(at, at + 32));
+}
+/** A fetch that always carries a timeout (the SDK's own requests have none). */
+export function timedFetch(timeoutMs, base = fetch) {
+    return ((input, init = {}) => {
+        const t = AbortSignal.timeout(timeoutMs);
+        const signal = init.signal ? AbortSignal.any([init.signal, t]) : t;
+        return base(input, { ...init, signal });
+    });
+}
+const execFile = (binary, args) => new Promise((resolve) => {
+    try {
+        const c = spawn(binary, args, { stdio: ["ignore", "pipe", "ignore"], timeout: 10_000 });
+        let out = "";
+        c.stdout.on("data", (d) => (out += d));
+        c.on("error", () => resolve({ status: 127, stdout: "" }));
+        c.on("close", (code) => resolve({ status: code ?? 1, stdout: out }));
+    }
+    catch {
+        resolve({ status: 127, stdout: "" });
+    }
+});
+/** base64 PKCS#8 DER (the CLI's single-line form) or PEM -> PEM, checked to be a P-256 private key. */
+export function toPem(stored) {
+    const pem = stored.includes("BEGIN") ? stored : `-----BEGIN PRIVATE KEY-----\n${stored.replace(/\s+/g, "").replace(/(.{64})/g, "$1\n").replace(/\n$/, "")}\n-----END PRIVATE KEY-----\n`;
+    const k = createPrivateKey(pem);
+    if (k.asymmetricKeyType !== "ec" || k.asymmetricKeyDetails?.namedCurve !== "prime256v1")
+        throw new Error("signer key is not P-256");
+    return pem;
+}
+/**
+ * The Candle CLI's own signer storage (OS keychain, service tv.candle.cli):
+ *  - a TEE wallet bound to the API key signs with the KEY signer (`candle tee signer new --key <prefix>`): keychain
+ *    account `key_signer_<keyPrefix>_<spkiSha256>`, indexed in ~/.config/candle/config.json `keySigners.entries`
+ *    by keyPrefix and signerQuorumId;
+ *  - an imported linked wallet signs with its own wallet signer: account `wallet_signer_<linkedWalletId>`.
+ * get(linkedWalletId) returns the key signer when the wallet is the resolved TEE wallet, else the wallet signer.
+ * The stored key's public key is checked against the index's spkiSha256. Nothing secret is ever logged.
+ */
+export class CandleCliSignerStore {
+    exec;
+    backend;
+    configPath;
+    keySigner = null;
+    constructor(opts = {}) {
+        this.exec = opts.exec ?? execFile;
+        this.backend = opts.backend ?? (process.platform === "darwin" ? "security" : "secret-tool");
+        this.configPath = opts.configPath ?? join(homedir(), ".config", "candle", "config.json");
+    }
+    forTeeWallet(linkedWalletId, keyPrefix, quorumId) {
+        this.keySigner = { linkedWalletId, keyPrefix, quorumId };
+        return this;
+    }
+    async read(account) {
+        const r = this.backend === "security"
+            ? await this.exec("security", ["find-generic-password", "-s", "tv.candle.cli", "-a", account, "-w"])
+            : await this.exec("secret-tool", ["lookup", "service", "tv.candle.cli", "account", account]);
+        const v = r.stdout.trim();
+        return r.status === 0 && v ? v : null;
+    }
+    async get(walletRef) {
+        if (this.keySigner && walletRef === this.keySigner.linkedWalletId) {
+            let entries = [];
+            try {
+                entries = JSON.parse(readFileSync(this.configPath, "utf8"))?.keySigners?.entries ?? [];
+            }
+            catch {
+                return null;
+            }
+            const ks = this.keySigner;
+            const mine = entries.filter((e) => e && e.keyPrefix === ks.keyPrefix && (!ks.quorumId || e.signerQuorumId === ks.quorumId));
+            if (mine.length !== 1 || !/^[0-9a-f]{64}$/.test(String(mine[0].spkiSha256)))
+                return null;
+            const stored = await this.read(`key_signer_${ks.keyPrefix}_${mine[0].spkiSha256}`);
+            if (!stored)
+                return null;
+            const pem = toPem(stored);
+            addSecret(stored);
+            const spki = createPublicKey(pem).export({ type: "spki", format: "der" });
+            if (createHash("sha256").update(spki).digest("hex") !== mine[0].spkiSha256)
+                throw new Error("key signer in the keychain does not match the CLI's index");
+            return pem;
+        }
+        const stored = await this.read(`wallet_signer_${walletRef}`);
+        if (!stored)
+            return null;
+        addSecret(stored);
+        return toPem(stored);
+    }
+    async set() {
+        throw new Error("read-only: signers are created with the Candle CLI");
+    }
+    async delete() {
+        throw new Error("read-only");
+    }
+}
+export async function makeSecretStore(cfg, w, env = process.env) {
+    const s = cfg.signer;
+    if (!s)
+        throw new Error("config.signer is required to trade");
+    if (s.store === "keychain")
+        return new CandleCliSignerStore().forTeeWallet(w.linkedWalletId, w.keyPrefix, w.signerQuorumId);
+    if (s.store === "file") {
+        const pass = env[s.passphraseEnv];
+        if (!pass)
+            throw new Error(`signer.passphraseEnv: ${s.passphraseEnv} is not set`);
+        addSecret(pass);
+        return new EncryptedFileSecretStore(s.path, pass);
+    }
+    const pem = env[s.pemEnv];
+    if (!pem)
+        throw new Error(`signer.pemEnv: ${s.pemEnv} is not set`);
+    addSecret(pem);
+    for (const line of pem.split(/\s+/))
+        if (line.length >= 16 && !line.startsWith("-----"))
+            addSecret(line);
+    const m = new InMemorySecretStore();
+    await m.set(w.linkedWalletId, toPem(pem));
+    return m;
+}
+/**
+ * The TEE wallet this API key may trade from (GET /api/v1/agent/wallets/trading, every page), with the key's prefix
+ * and Candle's Privy app id from the same answer. Config pins (linkedWalletId, privyWalletId, privyAppId) must match.
+ */
+export async function resolveWallet(cfg, apiKey, f = fetch) {
+    const get = async (path) => {
+        const r = await f(cfg.apiUrl + path, { headers: { "x-api-key": apiKey, accept: "application/json" }, signal: AbortSignal.timeout(20_000) });
+        if (!r.ok)
+            throw new Error(`GET ${path.split("?")[0]}: HTTP ${r.status}`);
+        return (await r.json());
+    };
+    const rows = [];
+    let head = null;
+    let cursor = null;
+    for (let page = 0; page < 20; page++) {
+        const body = await get(`/api/v1/agent/wallets/trading${cursor ? `?cursor=${encodeURIComponent(cursor)}` : ""}`);
+        head ??= body;
+        rows.push(...(body.page ?? []));
+        if (body.isDone !== false || !body.continueCursor)
+            break;
+        cursor = body.continueCursor;
+    }
+    const row = rows.find((r) => r.address === cfg.wallet && r.chain === "solana" && r.active !== false);
+    if (!row)
+        throw new Error(`wallet ${cfg.wallet} is not a TEE wallet this API key can trade from (GET /api/v1/agent/wallets/trading)`);
+    const id = row.id ?? row._id;
+    if (!id || !row.privyWalletId)
+        throw new Error(`wallet ${cfg.wallet}: Candle returned no wallet id or Privy wallet id`);
+    const appId = head?.privyAppId ?? cfg.privyAppId;
+    if (!appId)
+        throw new Error("Candle returned no privyAppId for this key; set config.privyAppId");
+    if (cfg.privyAppId && cfg.privyAppId !== appId)
+        throw new Error("config.privyAppId does not match the one Candle returns for this key");
+    if (cfg.linkedWalletId && cfg.linkedWalletId !== id)
+        throw new Error("config.linkedWalletId does not match the wallet's row");
+    if (cfg.privyWalletId && cfg.privyWalletId !== row.privyWalletId)
+        throw new Error("config.privyWalletId does not match the wallet's row");
+    let quorum = row.signerQuorumId ?? null;
+    if (!quorum) {
+        try {
+            const all = await get("/api/v1/agent/wallets");
+            quorum = (all.page ?? []).find((r) => (r._id ?? r.id) === id)?.signerQuorumId ?? null;
+        }
+        catch {
+            quorum = null;
+        }
+    }
+    return { linkedWalletId: id, privyWalletId: row.privyWalletId, keyPrefix: String(head?.keyPrefix ?? ""), privyAppId: appId, signerQuorumId: quorum };
+}
+/**
+ * The account's embedded wallet: GET /api/v1/agent/wallets/embedded must name `wallet` as its Solana address, and the
+ * key must not be denied the wallet (embeddedWalletPermission) nor the wallet undelegated (Candle could not sign).
+ */
+export async function resolveEmbedded(cfg, apiKey, f = fetch) {
+    const r = await f(cfg.apiUrl + "/api/v1/agent/wallets/embedded", { headers: { "x-api-key": apiKey, accept: "application/json" }, signal: AbortSignal.timeout(20_000) });
+    if (!r.ok)
+        throw new Error(`GET /api/v1/agent/wallets/embedded: HTTP ${r.status}`);
+    const b = (await r.json());
+    const sol = b?.wallets?.solana ?? {};
+    if (sol.address !== cfg.wallet)
+        throw new Error(`wallet ${cfg.wallet} is not this API key's embedded Solana wallet (Candle names ${sol.address ?? "none"})`);
+    if (b?.embeddedWalletPermission === "denied")
+        throw new Error("this API key is denied the embedded wallet (embeddedWalletPermission: denied)");
+    if (sol.delegated === false)
+        throw new Error("the embedded wallet is not delegated: Candle cannot sign for it");
+    return { address: sol.address, permission: b?.embeddedWalletPermission ?? null };
+}
+/** payer main: buildTrade executes the trade inside the call (Candle signs and broadcasts); there is nothing to sign here. */
+export class EmbeddedRail {
+    payer = { type: "main" };
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    build(req) {
+        return this.client.buildTrade(req);
+    }
+    async sign() {
+        throw Object.assign(new Error("payer main has nothing to sign"), { code: "NOT_SIGNABLE", status: 400 });
+    }
+    async submit() {
+        throw Object.assign(new Error("payer main has nothing to submit"), { code: "NOT_SUBMITTABLE", status: 400 });
+    }
+    confirm(clientTradeId, signature) {
+        return this.client.confirmTrade({ clientTradeId, signature });
+    }
+    async job(clientTradeId) {
+        try {
+            return await this.client.getTradeJob(clientTradeId);
+        }
+        catch (e) {
+            if (e?.code === "JOB_NOT_FOUND")
+                return null;
+            throw e;
+        }
+    }
+}
+export class SdkRail {
+    payer;
+    client;
+    w;
+    constructor(client, wallet) {
+        this.client = client;
+        this.w = wallet;
+        this.payer = { type: "linked", linkedWalletId: wallet.linkedWalletId };
+    }
+    build(req) {
+        return this.client.buildTrade(req);
+    }
+    async sign(unsignedTransactionBase64) {
+        const r = await this.client.signLinkedTransaction({ linkedWalletId: this.w.linkedWalletId, privyWalletId: this.w.privyWalletId, chain: "solana", unsignedTransactionBase64 });
+        if (r.encoding && r.encoding !== "base64")
+            throw new Error(`sign relay returned encoding ${r.encoding}`);
+        return r.signedTransaction;
+    }
+    submit(clientTradeId, signed) {
+        return this.client.submit({ clientTradeId, signedTransactions: [signed] });
+    }
+    confirm(clientTradeId, signature) {
+        return this.client.confirmTrade({ clientTradeId, signature });
+    }
+    async job(clientTradeId) {
+        try {
+            return await this.client.getTradeJob(clientTradeId);
+        }
+        catch (e) {
+            if (e?.code === "JOB_NOT_FOUND")
+                return null;
+            throw e;
+        }
+    }
+}

package/dist/filters.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Entry filters. A verdict is `buy`, `skip` (final, with a reason), or `wait` (a field the filter needs is
+ * not known yet: retried each cycle until it is, or the coin ages past maxAgeSec). Unknown never passes.
+ */
+import type { Config } from "./config.ts";
+import type { Launch } from "./detect/detector.ts";
+import type { CandleCurve } from "./market/curve.ts";
+export type Verdict = {
+    verdict: "buy";
+    impactBps: number;
+    expectedOutRaw: bigint;
+} | {
+    verdict: "skip";
+    reason: string;
+} | {
+    verdict: "wait";
+    reason: string;
+};
+export interface Caps {
+    open: number;
+    entriesForMint: number;
+    lifetimeLamports: bigint;
+    paused: boolean;
+}
+export declare function lamportsOf(sol: number): bigint;
+export declare function evaluate(cfg: Config, l: Launch, curve: CandleCurve | null | "unreadable", caps: Caps, nowMs: number): Verdict;

package/dist/filters.js

@@ -0,0 +1,92 @@
+import { buyImpact, curveClass } from "./market/curve.js";
+import { WSOL } from "./solana/pda.js";
+export function lamportsOf(sol) {
+    return BigInt(Math.round(sol * 1e9));
+}
+export function evaluate(cfg, l, curve, caps, nowMs) {
+    const f = cfg.filters;
+    if (!f.chains.includes(l.chain))
+        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` };
+    // The bot never buys a launch by its own wallet.
+    if (l.creator === cfg.wallet || l.signer === cfg.wallet)
+        return { verdict: "skip", reason: "own wallet's launch" };
+    if (f.creatorDeny?.length) {
+        const who = [l.creator, l.signer].filter(Boolean);
+        if (who.some((w) => f.creatorDeny.includes(w)))
+            return { verdict: "skip", reason: "creator denied" };
+        if (!l.creator)
+            return { verdict: "wait", reason: "creator unknown (deny list)" };
+    }
+    if (f.creatorAllow?.length) {
+        const who = [l.creator, l.signer].filter(Boolean);
+        if (!who.some((w) => f.creatorAllow.includes(w)))
+            return l.creator ? { verdict: "skip", reason: "creator not allowed" } : { verdict: "wait", reason: "creator unknown (allow list)" };
+    }
+    if (!l.launchMode) {
+        // A chain-first launch: Candle's list may not have it yet. The curve account says open / exclusive / exp-*.
+        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}` };
+    if (f.nameMatch) {
+        if (l.name === undefined)
+            return { verdict: "wait", reason: "name unknown" };
+        if (!new RegExp(f.nameMatch, "i").test(l.name))
+            return { verdict: "skip", reason: "name does not match" };
+    }
+    if (f.symbolMatch) {
+        if (l.symbol === undefined)
+            return { verdict: "wait", reason: "symbol unknown" };
+        if (!new RegExp(f.symbolMatch, "i").test(l.symbol))
+            return { verdict: "skip", reason: "symbol does not match" };
+    }
+    if (caps.paused)
+        return { verdict: "skip", reason: "PAUSE_BUYS" };
+    if (caps.entriesForMint >= cfg.buy.maxPerCoin)
+        return { verdict: "skip", reason: `maxPerCoin ${cfg.buy.maxPerCoin}` };
+    if (caps.open >= cfg.buy.maxOpen)
+        return { verdict: "skip", reason: `maxOpen ${cfg.buy.maxOpen}` };
+    const ticket = lamportsOf(cfg.buy.sol);
+    if (caps.lifetimeLamports + ticket > lamportsOf(cfg.buy.lifetimeSol))
+        return { verdict: "skip", reason: `lifetimeSol ${cfg.buy.lifetimeSol}` };
+    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 impact;
+    let expectedOutRaw;
+    try {
+        const r = buyImpact(curve, ticket);
+        impact = r.impactBps;
+        expectedOutRaw = r.expectedOutRaw;
+    }
+    catch (e) {
+        return { verdict: "skip", reason: e.message };
+    }
+    if (impact > f.maxImpactBps)
+        return { verdict: "skip", reason: `impact ${impact} bps > ${f.maxImpactBps}` };
+    return { verdict: "buy", impactBps: impact, expectedOutRaw };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+/** Library entry: the types a custom exit strategy is written against, and the config parser. */
+export type { Decision, ExitStrategy, MarketView, PositionView, StrategyFactory } from "./strategies/types.ts";
+export { HOLD, StrategyConfigError } from "./strategies/types.ts";
+export { parseConfig, loadConfig, ConfigError, LAUNCH_MODES } from "./config.ts";
+export type { Config } from "./config.ts";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { HOLD, StrategyConfigError } from "./strategies/types.js";
+export { parseConfig, loadConfig, ConfigError, LAUNCH_MODES } from "./config.js";

package/dist/init.d.ts

@@ -0,0 +1,23 @@
+/** A valid address that is nobody's wallet: lets a dry run start before a wallet is chosen. */
+export declare const PLACEHOLDER_WALLET = "11111111111111111111111111111111";
+export interface InitIO {
+    env: Record<string, string | undefined>;
+    fetch: typeof fetch;
+    out: (s: string) => void;
+    /** Ask a question (interactive only). Returns the answer, or the default on an empty line. */
+    ask?: (q: string, def: string) => Promise<string>;
+}
+type Opt = Record<string, string>;
+/** Build the config object from flags (and answers), validate it, and return it with notes for the user. */
+export declare function buildInitConfig(opt: Opt, io: InitIO): Promise<{
+    config: Record<string, unknown>;
+    notes: string[];
+}>;
+/** The `init` command. Returns a process exit code. */
+export declare function init(opt: Opt, io: InitIO): Promise<number>;
+/** Terminal prompts for `init` (only when stdin is a TTY and --yes is not given). */
+export declare function terminalAsk(): {
+    ask: (q: string, def: string) => Promise<string>;
+    close: () => void;
+};
+export {};