@potswap_io/mcp 0.0.0-stage → 0.2.0

package/dist/server.js

@@ -0,0 +1,201 @@
+// PRD P10 — the Potswap MCP server. Tools are thin, safe wrappers over the Potswap API.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Connection, PublicKey } from '@solana/web3.js';
+import { z } from 'zod';
+import { PotswapApi, ApiError } from './api.js';
+import { loadConfig, NO_WALLET, SOL_MINT, USDC_MINT } from './config.js';
+import { buildQuote, executeSwap } from './trade.js';
+import { redact, redactValue } from './redact.js';
+import { loadSigner } from './wallet.js';
+import { riskBadges, riskLevel } from './shared/risk.js';
+import { registerStrategyTools } from './strategies/tools.js';
+export const VERSION = '0.2.0';
+const ok = (data, summary) => ({
+    content: [{ type: 'text', text: redact(summary ?? JSON.stringify(data, null, 2)) }], structuredContent: redactValue(data),
+});
+const fail = (message, extra = {}) => ({
+    content: [{ type: 'text', text: redact(message) }], structuredContent: redactValue({ error: message, ...extra }), isError: true,
+});
+export function createServer(deps = {}) {
+    const config = deps.config ?? loadConfig();
+    const signer = deps.signer !== undefined ? deps.signer : loadSigner(config);
+    const api = new PotswapApi(config.apiBase, deps.fetchFn);
+    const readBalances = deps.balances ?? rpcBalances(config.rpcUrl);
+    const trade = { api, config, signer, balances: readBalances };
+    const server = new McpServer({ name: 'potswap', version: VERSION });
+    const walletOr = (w) => w ?? signer?.publicKey ?? null;
+    server.registerTool('search_tokens', {
+        title: 'Search Solana tokens',
+        description: 'Find tokens by name, symbol or mint address. Returns up to 20 with price, market cap and liquidity.',
+        inputSchema: { query: z.string().min(1).max(64) },
+    }, async ({ query }) => {
+        try {
+            const list = (await api.searchTokens(query)).slice(0, 20);
+            const tokens = list.map(slimToken);
+            return ok({ tokens }, tokens.map((t) => `${t.symbol} (${t.name}) ${t.mint} price=${t.usdPrice ?? '?'} mcap=${t.mcap ?? '?'}${t.isVerified ? ' ✓' : ''}`).join('\n') || 'No tokens found');
+        }
+        catch (e) {
+            return fail(msg(e));
+        }
+    });
+    server.registerTool('get_token', {
+        title: 'Token details and risk flags',
+        description: 'Full token record: price, mcap, liquidity, holders, 5m/1h/6h/24h stats, audit data and risk badges (riskLevel 0 safe … 3 danger).',
+        inputSchema: { mint: z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/) },
+    }, async ({ mint }) => {
+        try {
+            const t = await api.terminalToken(mint);
+            const badges = riskBadges(t);
+            return ok({ token: t, riskBadges: badges, riskLevel: riskLevel(badges) }, `${t.symbol} (${t.name})\nprice=${t.usdPrice} mcap=${t.mcap} liquidity=${t.liquidity} holders=${t.holderCount}\nrisk ${riskLevel(badges)}/3: ${badges.map((b) => b.label).join(', ')}`);
+        }
+        catch (e) {
+            return fail(msg(e));
+        }
+    });
+    server.registerTool('get_trending', {
+        title: 'Trending / new / top / graduating tokens',
+        description: 'Discovery lists from Potswap (edge-cached, refreshed every 15 s).',
+        inputSchema: { kind: z.enum(['new', 'trending', 'top', 'graduating']).default('trending'), limit: z.number().int().min(1).max(50).default(20) },
+    }, async ({ kind, limit }) => {
+        try {
+            const list = (await api.list(kind)).slice(0, limit);
+            const rows = list.map((t) => ({ mint: t.id, symbol: t.symbol, name: t.name, usdPrice: t.usdPrice, mcap: t.mcap, liquidity: t.liquidity, holders: t.holderCount, change5m: t.stats5m?.priceChange, change1h: t.stats1h?.priceChange, bondingProgress: t.bondingProgress, riskLevel: riskLevel(riskBadges(t)) }));
+            return ok({ kind, tokens: rows }, rows.map((r) => `${r.symbol} ${r.mint} mcap=${r.mcap} 5m=${r.change5m} risk=${r.riskLevel}`).join('\n'));
+        }
+        catch (e) {
+            return fail(msg(e));
+        }
+    });
+    server.registerTool('get_quote', {
+        title: 'Get a swap quote',
+        description: 'Best route across Metis, JupiterZ, DFlow and OKX. Amount is in UI units of the input token (1 = 1 SOL). Includes the Potswap fee (returned to the wallet as POT points).',
+        inputSchema: quoteShape,
+    }, async (a) => {
+        try {
+            const q = await buildQuote(api, a);
+            return ok({ ...q }, `${a.amount} ${q.inputSymbol} → ${q.outAmount} ${q.outputSymbol} via ${q.router} (fee ${q.feeLabel ?? `${q.feeBps} bps`}, impact ${q.priceImpactPct}%)`);
+        }
+        catch (e) {
+            return fail(msg(e));
+        }
+    });
+    server.registerTool('swap', {
+        title: 'Swap tokens (signs with the agent wallet)',
+        description: 'Executes a swap at the best route. Requires confirm=true; otherwise returns the quote only. Protected by POTSWAP_MAX_TRADE_SOL and POTSWAP_MAX_SLIPPAGE_BPS. Every error states whether funds were debited.',
+        inputSchema: { ...quoteShape, confirm: z.boolean().default(false), maxSlippageBps: z.number().int().min(1).max(5000).optional() },
+    }, async (a) => {
+        const out = await executeSwap(trade, { inputMint: a.inputMint, outputMint: a.outputMint, amount: a.amount, slippageBps: a.slippageBps ?? a.maxSlippageBps, confirm: a.confirm });
+        switch (out.kind) {
+            case 'no-wallet': return fail(out.message);
+            case 'refused': return fail(out.message, { quote: out.quote });
+            case 'quote-only': return ok({ confirmRequired: true, quote: out.quote }, `Quote only (confirm=true to execute): ${a.amount} ${out.quote.inputSymbol} → ${out.quote.outAmount} ${out.quote.outputSymbol} via ${out.quote.router}`);
+            case 'dry-run': return ok({ dryRun: true, quote: out.quote }, `DRY RUN, nothing signed: ${a.amount} ${out.quote.inputSymbol} → ${out.quote.outAmount} ${out.quote.outputSymbol}`);
+            case 'failed': return fail(out.message, { signature: out.signature, explorerUrl: out.explorerUrl, quote: out.quote });
+            case 'ok': return ok({ ...out.result }, `Swapped ${a.amount} ${out.result.inputSymbol} → ${out.result.outAmount} ${out.result.outputSymbol} via ${out.result.router}. ${out.result.explorerUrl}`);
+        }
+    });
+    server.registerTool('get_balances', {
+        title: 'Wallet balances',
+        description: 'SOL and SPL token balances with USD values. Defaults to the agent wallet.',
+        inputSchema: { wallet: z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/).optional() },
+    }, async ({ wallet }) => {
+        const w = walletOr(wallet);
+        if (!w)
+            return fail(NO_WALLET);
+        try {
+            const bal = await readBalances(w);
+            const mints = Object.keys(bal);
+            const prices = await api.prices(mints.slice(0, 50)).catch(() => ({}));
+            const rows = mints.map((m) => ({ mint: m, amount: bal[m], usd: prices[m] ? bal[m] * prices[m] : undefined })).sort((x, y) => (y.usd ?? 0) - (x.usd ?? 0));
+            const total = rows.reduce((s, r) => s + (r.usd ?? 0), 0);
+            return ok({ wallet: w, totalUsd: total, balances: rows }, `${w}\ntotal ≈ $${total.toFixed(2)}\n` + rows.map((r) => `${r.mint === SOL_MINT ? 'SOL' : r.mint}: ${r.amount}${r.usd !== undefined ? ` ($${r.usd.toFixed(2)})` : ''}`).join('\n'));
+        }
+        catch (e) {
+            return fail(msg(e));
+        }
+    });
+    server.registerTool('get_positions', {
+        title: 'Positions',
+        description: 'Token holdings with 24h price change (PnL arrives in a later version).',
+        inputSchema: { wallet: z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/).optional() },
+    }, async ({ wallet }) => {
+        const w = walletOr(wallet);
+        if (!w)
+            return fail(NO_WALLET);
+        try {
+            const bal = await readBalances(w);
+            const mints = Object.keys(bal).filter((m) => m !== SOL_MINT).slice(0, 20);
+            const infos = mints.length ? await api.searchTokens(mints.join(',')).catch(() => []) : [];
+            const prices = await api.prices([SOL_MINT, ...mints]).catch(() => ({}));
+            const positions = mints.map((m) => { const t = infos.find((x) => x.id === m); return { mint: m, symbol: t?.symbol ?? m.slice(0, 4), amount: bal[m], usd: prices[m] ? bal[m] * prices[m] : undefined }; });
+            return ok({ wallet: w, sol: bal[SOL_MINT] ?? 0, solUsd: prices[SOL_MINT] ? (bal[SOL_MINT] ?? 0) * prices[SOL_MINT] : undefined, positions });
+        }
+        catch (e) {
+            return fail(msg(e));
+        }
+    });
+    server.registerTool('get_points', {
+        title: 'POT points',
+        description: "Season 1 points for a wallet: this epoch, all-time, POT allocated and claimable, next unlock. Defaults to the agent wallet.",
+        inputSchema: { wallet: z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/).optional() },
+    }, async ({ wallet }) => {
+        const w = walletOr(wallet);
+        if (!w)
+            return fail(NO_WALLET);
+        try {
+            return ok({ enabled: true, ...(await api.points(w)) });
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.status === 503)
+                return ok({ enabled: false, wallet: w, note: 'The points engine is not enabled yet. Swaps made now still pay the Potswap fee; points start with Season 1.' });
+            return fail(msg(e));
+        }
+    });
+    server.registerTool('get_leaderboard', {
+        title: 'Leaderboard',
+        description: 'Top wallets by Potswap fee paid, with POT allocated.',
+        inputSchema: {},
+    }, async () => {
+        try {
+            return ok({ enabled: true, ...(await api.leaderboard()) });
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.status === 503)
+                return ok({ enabled: false, note: 'The points engine is not enabled yet.' });
+            return fail(msg(e));
+        }
+    });
+    registerStrategyTools(server, { trade, store: deps.strategyStore, scheduler: deps.scheduler });
+    return server;
+}
+const quoteShape = {
+    inputMint: z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/).describe('Mint of the token to sell (SOL = So11111111111111111111111111111111111111112)'),
+    outputMint: z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/).describe('Mint of the token to buy'),
+    amount: z.number().positive().describe('Amount in UI units of the input token (1 = 1 SOL)'),
+    slippageBps: z.number().int().min(1).max(5000).optional().describe('Fixed slippage in bps; omit for auto'),
+};
+function slimToken(t) {
+    return { mint: t.id, symbol: t.symbol, name: t.name, decimals: t.decimals, usdPrice: t.usdPrice, mcap: t.mcap, liquidity: t.liquidity, isVerified: t.isVerified ?? false };
+}
+function msg(e) { return e instanceof Error ? e.message : String(e); }
+function rpcBalances(rpcUrl) {
+    return async (wallet) => {
+        const conn = new Connection(rpcUrl, 'confirmed');
+        const owner = new PublicKey(wallet);
+        const out = {};
+        const [lamports, spl, t22] = await Promise.all([
+            conn.getBalance(owner),
+            conn.getParsedTokenAccountsByOwner(owner, { programId: new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA') }),
+            conn.getParsedTokenAccountsByOwner(owner, { programId: new PublicKey('TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb') }).catch(() => ({ value: [] })),
+        ]);
+        out[SOL_MINT] = lamports / 1e9;
+        for (const { account } of [...spl.value, ...t22.value]) {
+            const info = account.data.parsed?.info;
+            const ui = Number(info?.tokenAmount?.uiAmount ?? 0);
+            if (info && ui > 0)
+                out[info.mint] = (out[info.mint] ?? 0) + ui;
+        }
+        return out;
+    };
+}
+export { SOL_MINT, USDC_MINT };

package/dist/shared/errors.d.ts

@@ -0,0 +1,5 @@
+import type { OrderResponse } from './lib-types.js';
+/** Maps /order error codes (transaction empty) to user copy. */
+export declare function describeOrderError(o: Pick<OrderResponse, 'errorCode' | 'errorMessage'>): string;
+/** User-facing error copy. Every message states whether funds were debited. */
+export declare function friendlyError(msg: string): string;

package/dist/shared/errors.js

@@ -0,0 +1,24 @@
+/** Maps /order error codes (transaction empty) to user copy. */
+export function describeOrderError(o) {
+    const map = {
+        1: 'Insufficient balance for this swap.',
+        2: 'Not enough SOL to pay network fees. Keep at least 0.01 SOL.',
+        3: 'Amount too small for this route. Try a larger amount.',
+    };
+    return (o.errorCode && map[o.errorCode]) || o.errorMessage || 'Could not build the swap. Try again.';
+}
+/** User-facing error copy. Every message states whether funds were debited. */
+export function friendlyError(msg) {
+    const m = msg.toLowerCase();
+    if (m.includes('user rejected') || m.includes('rejected the request'))
+        return 'You rejected the transaction in your wallet. No funds were debited.';
+    if (m.includes('slippage') || m.includes('0x1771') || m.includes('6001'))
+        return 'Price moved beyond your slippage tolerance. No funds were debited. Try again or raise slippage in settings.';
+    if (m.includes('insufficient'))
+        return 'Insufficient balance for this swap, including network fees. No funds were debited.';
+    if (m.includes('expired') || m.includes('-1005') || m.includes('block height'))
+        return 'The quote expired before the transaction landed. No funds were debited. Please try again.';
+    if (m.includes('failed to land') || m.includes('-1000'))
+        return 'The network was congested and the transaction did not land. No funds were debited. Please try again.';
+    return `${msg} If the transaction did not land, no funds were debited.`;
+}

package/dist/shared/fee.d.ts

@@ -0,0 +1,24 @@
+export interface FeeSchedule {
+    standardBps: number;
+    sizeBps: number;
+    sizeThresholdUsd: number;
+    stakerDiscountBps: number;
+    /** POT that must be staked for the discount; null until TGE (discount disabled). */
+    stakerMinPot: number | null;
+}
+export declare const JUP_MIN_BPS = 50;
+export declare const JUP_MAX_BPS = 255;
+export declare const DEFAULT_FEE_SCHEDULE: FeeSchedule;
+export type FeeTier = 'standard' | 'size' | 'staker';
+export interface FeeDecision {
+    bps: number;
+    tier: FeeTier;
+    label: string;
+}
+/**
+ * @param inputUsd USD value of the input amount at quote time; undefined when no price is known (→ standard tier)
+ * @param stakedPot POT staked by the wallet; 0 / undefined when unknown
+ */
+export declare function feeBpsFor(schedule: FeeSchedule, inputUsd?: number, stakedPot?: number): FeeDecision;
+/** Parses the schedule from /api/config, falling back to defaults field by field. */
+export declare function parseFeeSchedule(raw: unknown): FeeSchedule;

package/dist/shared/fee.js

@@ -0,0 +1,42 @@
+// GENERATED by scripts/sync-shared.mjs from app/src/lib/fee.ts. Do not edit here.
+// PRD P8.12–P8.15 — the fee schedule. One pure function shared by the web app and the MCP
+// (mcp/src/shared/fee.ts is a generated copy). Jupiter allows 50–255 bps.
+export const JUP_MIN_BPS = 50;
+export const JUP_MAX_BPS = 255;
+export const DEFAULT_FEE_SCHEDULE = {
+    standardBps: 250,
+    sizeBps: 100,
+    sizeThresholdUsd: 1000,
+    stakerDiscountBps: 100,
+    stakerMinPot: null,
+};
+const clamp = (bps) => Math.min(JUP_MAX_BPS, Math.max(JUP_MIN_BPS, Math.round(bps)));
+/**
+ * @param inputUsd USD value of the input amount at quote time; undefined when no price is known (→ standard tier)
+ * @param stakedPot POT staked by the wallet; 0 / undefined when unknown
+ */
+export function feeBpsFor(schedule, inputUsd, stakedPot = 0) {
+    const size = inputUsd !== undefined && inputUsd >= schedule.sizeThresholdUsd;
+    let bps = size ? schedule.sizeBps : schedule.standardBps;
+    let tier = size ? 'size' : 'standard';
+    if (schedule.stakerMinPot !== null && stakedPot >= schedule.stakerMinPot) {
+        bps -= schedule.stakerDiscountBps;
+        tier = 'staker';
+    }
+    bps = clamp(bps);
+    const pct = `${bps / 100}%`;
+    const label = tier === 'standard' ? pct : tier === 'size' ? `${pct} (size tier)` : `${pct} (staker)`;
+    return { bps, tier, label };
+}
+/** Parses the schedule from /api/config, falling back to defaults field by field. */
+export function parseFeeSchedule(raw) {
+    const r = (raw ?? {});
+    const num = (v, d) => (typeof v === 'number' && Number.isFinite(v) ? v : d);
+    return {
+        standardBps: clamp(num(r.standardBps, DEFAULT_FEE_SCHEDULE.standardBps)),
+        sizeBps: clamp(num(r.sizeBps, DEFAULT_FEE_SCHEDULE.sizeBps)),
+        sizeThresholdUsd: num(r.sizeThresholdUsd, DEFAULT_FEE_SCHEDULE.sizeThresholdUsd),
+        stakerDiscountBps: num(r.stakerDiscountBps, DEFAULT_FEE_SCHEDULE.stakerDiscountBps),
+        stakerMinPot: typeof r.stakerMinPot === 'number' && r.stakerMinPot > 0 ? r.stakerMinPot : null,
+    };
+}

package/dist/shared/lib-types.d.ts

@@ -0,0 +1,42 @@
+export interface Token {
+    id: string;
+    symbol: string;
+    name: string;
+    icon?: string;
+    decimals: number;
+    isVerified?: boolean;
+    usdPrice?: number;
+}
+export interface OrderResponse {
+    router: 'metis' | 'jupiterz' | 'dflow' | 'okx' | string;
+    inAmount: string;
+    outAmount: string;
+    inUsdValue?: number;
+    outUsdValue?: number;
+    priceImpactPct?: string | number;
+    slippageBps?: number;
+    feeBps?: number;
+    feeMint?: string;
+    platformFee?: {
+        amount: string;
+        feeBps: number;
+        feeMint: string;
+    };
+    transaction: string | null;
+    requestId: string;
+    lastValidBlockHeight?: number;
+    expireAt?: string;
+    errorCode?: number;
+    errorMessage?: string;
+    mode?: string;
+    transactionVersion?: number;
+}
+export interface ExecuteResponse {
+    status: 'Success' | 'Failed';
+    signature?: string;
+    code: number;
+    error?: string;
+    totalInputAmount?: string;
+    totalOutputAmount?: string;
+}
+export type SwapStage = 'idle' | 'signing' | 'sending' | 'confirming' | 'success' | 'failed';

package/dist/shared/lib-types.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/risk.d.ts

@@ -0,0 +1,15 @@
+import type { TerminalToken } from './types.js';
+export type Tone = 'good' | 'warn' | 'bad' | 'muted';
+export interface Badge {
+    key: string;
+    icon: string;
+    label: string;
+    tone: Tone;
+    tip: string;
+}
+export declare const TOP_HOLDER_WARN = 30;
+export declare const DEV_BALANCE_WARN = 10;
+export declare const DEV_MINTS_WARN = 20;
+export declare function riskBadges(t: Pick<TerminalToken, 'audit' | 'isVerified'>): Badge[];
+/** 0 (safe) … 3 (danger) summary used for row colouring. */
+export declare function riskLevel(badges: Badge[]): number;

package/dist/shared/risk.js

@@ -0,0 +1,35 @@
+export const TOP_HOLDER_WARN = 30; // %
+export const DEV_BALANCE_WARN = 10; // %
+export const DEV_MINTS_WARN = 20;
+export function riskBadges(t) {
+    const a = t.audit;
+    if (!a)
+        return [{ key: 'unaudited', icon: '?', label: 'Unaudited', tone: 'muted', tip: 'No audit data for this token yet.' }];
+    const out = [];
+    out.push(a.mintAuthorityDisabled
+        ? { key: 'mint', icon: '🔒', label: 'Mint revoked', tone: 'good', tip: 'Nobody can mint more supply.' }
+        : { key: 'mint', icon: '🖨️', label: 'Mintable', tone: 'bad', tip: 'The creator can still mint new supply.' });
+    out.push(a.freezeAuthorityDisabled
+        ? { key: 'freeze', icon: '🧊', label: 'Freeze revoked', tone: 'good', tip: 'Token accounts cannot be frozen.' }
+        : { key: 'freeze', icon: '❄️', label: 'Freezable', tone: 'bad', tip: 'The creator can freeze your tokens.' });
+    if (a.topHoldersPercentage !== undefined && a.topHoldersPercentage > TOP_HOLDER_WARN) {
+        out.push({ key: 'top', icon: '⚠', label: `Top holders ${a.topHoldersPercentage.toFixed(0)}%`, tone: 'warn', tip: 'A few wallets hold a large share of the supply.' });
+    }
+    if (a.devBalancePercentage !== undefined && a.devBalancePercentage > DEV_BALANCE_WARN) {
+        out.push({ key: 'dev', icon: '🧑‍💻', label: `Dev holds ${a.devBalancePercentage.toFixed(0)}%`, tone: 'warn', tip: 'The deployer wallet still holds a large share.' });
+    }
+    if (a.devMints !== undefined && a.devMints > DEV_MINTS_WARN) {
+        out.push({ key: 'serial', icon: '🔁', label: `Dev launched ${a.devMints.toLocaleString()} tokens`, tone: 'bad', tip: 'This deployer has launched many tokens before.' });
+    }
+    if (t.isVerified)
+        out.push({ key: 'verified', icon: '✓', label: 'Verified', tone: 'good', tip: 'On Jupiter\'s verified list.' });
+    return out;
+}
+/** 0 (safe) … 3 (danger) summary used for row colouring. */
+export function riskLevel(badges) {
+    const bad = badges.filter((b) => b.tone === 'bad').length;
+    const warn = badges.filter((b) => b.tone === 'warn').length;
+    if (badges.some((b) => b.key === 'unaudited'))
+        return 1;
+    return Math.min(3, bad * 2 + warn);
+}

package/dist/shared/types.d.ts

@@ -0,0 +1,50 @@
+export interface TokenStats {
+    priceChange?: number;
+    buyVolume?: number;
+    sellVolume?: number;
+    numBuys?: number;
+    numSells?: number;
+    numTraders?: number;
+    numNetBuyers?: number;
+}
+export interface TokenAudit {
+    mintAuthorityDisabled?: boolean;
+    freezeAuthorityDisabled?: boolean;
+    topHoldersPercentage?: number;
+    devBalancePercentage?: number;
+    devMigrations?: number;
+    devMints?: number;
+}
+export interface TerminalToken {
+    id: string;
+    symbol: string;
+    name: string;
+    icon?: string;
+    decimals: number;
+    usdPrice?: number;
+    mcap?: number;
+    fdv?: number;
+    liquidity?: number;
+    holderCount?: number;
+    organicScore?: number;
+    organicScoreLabel?: string;
+    launchpad?: string;
+    graduatedPool?: string;
+    graduatedAt?: string;
+    firstPool?: {
+        id: string;
+        createdAt: string;
+    };
+    createdAt?: string;
+    tags?: string[];
+    audit?: TokenAudit;
+    stats5m?: TokenStats;
+    stats1h?: TokenStats;
+    stats6h?: TokenStats;
+    stats24h?: TokenStats;
+    isVerified?: boolean;
+    /** Added by the graduating list: estimated bonding-curve progress 0–1. */
+    bondingProgress?: number;
+}
+export type ListKind = 'new' | 'trending' | 'top' | 'graduating';
+export declare const LIST_KINDS: ListKind[];

package/dist/shared/types.js

@@ -0,0 +1 @@
+export const LIST_KINDS = ['new', 'trending', 'top', 'graduating'];

package/dist/strategies/engine.d.ts

@@ -0,0 +1,40 @@
+import type { DcaStrategy, RebalanceStrategy, Run, Strategy, TpSlStrategy } from './types.js';
+export declare const SOL_MINT = "So11111111111111111111111111111111111111112";
+/** True when a time-based strategy should run at `now`. */
+export declare function isDue(s: Strategy, now: number): boolean;
+/**
+ * Next run after a run at `now`. A missed window runs once; the next slot is
+ * always in the future (P11.2), never a catch-up burst.
+ */
+export declare function nextRunAfter(s: DcaStrategy | RebalanceStrategy, now: number): string;
+export declare function dcaIsComplete(s: DcaStrategy): boolean;
+export interface Leg {
+    inputMint: string;
+    outputMint: string;
+    amount: number;
+    reason: string;
+}
+/**
+ * Rebalance plan (P11.4): weights from balances × prices; assets drifting more than
+ * `driftPct` points are brought back via SOL. Returns [] when nothing drifts.
+ * Unpriced targets are excluded and reported in `warnings`.
+ */
+export declare function rebalancePlan(s: RebalanceStrategy, balances: Record<string, number>, prices: Record<string, number>): {
+    legs: Leg[];
+    warnings: string[];
+    weights: Record<string, number>;
+};
+export type TpSlTrigger = {
+    trigger: 'take-profit' | 'stop-loss' | 'trailing-stop';
+    threshold: number;
+} | null;
+/** TP/SL decision (P11.5). `price` undefined = no decision. Returns the updated high-water mark too. */
+export declare function tpslDecision(s: TpSlStrategy, price: number | undefined): {
+    trigger: TpSlTrigger;
+    highWater: number;
+};
+/** SOL-equivalent spent by all strategies in the UTC day containing `now` (P11.6). */
+export declare function solSpentToday(runs: Run[], now: number): number;
+export declare function dcaLegFor(s: DcaStrategy): Leg;
+export declare const MAX_CONSECUTIVE_FAILURES = 3;
+export declare function newId(prefix: string, now?: number): string;

package/dist/strategies/engine.js

@@ -0,0 +1,100 @@
+export const SOL_MINT = 'So11111111111111111111111111111111111111112';
+const MIN = 60_000;
+/** True when a time-based strategy should run at `now`. */
+export function isDue(s, now) {
+    if (s.status !== 'active' || !s.nextRunAt)
+        return false;
+    return Date.parse(s.nextRunAt) <= now;
+}
+/**
+ * Next run after a run at `now`. A missed window runs once; the next slot is
+ * always in the future (P11.2), never a catch-up burst.
+ */
+export function nextRunAfter(s, now) {
+    const interval = (s.kind === 'dca' ? s.intervalMinutes : s.checkIntervalMinutes) * MIN;
+    return new Date(now + interval).toISOString();
+}
+export function dcaIsComplete(s) {
+    return s.totalRuns !== undefined && s.runsDone >= s.totalRuns;
+}
+/**
+ * Rebalance plan (P11.4): weights from balances × prices; assets drifting more than
+ * `driftPct` points are brought back via SOL. Returns [] when nothing drifts.
+ * Unpriced targets are excluded and reported in `warnings`.
+ */
+export function rebalancePlan(s, balances, prices) {
+    const warnings = [];
+    const mints = Object.keys(s.targets);
+    const priced = mints.filter((m) => prices[m] > 0);
+    for (const m of mints)
+        if (!(prices[m] > 0))
+            warnings.push(`No price for ${m}; it is excluded until one is available.`);
+    const values = Object.fromEntries(priced.map((m) => [m, (balances[m] ?? 0) * prices[m]]));
+    const total = Object.values(values).reduce((a, b) => a + b, 0);
+    const weights = {};
+    if (total <= 0)
+        return { legs: [], warnings, weights };
+    for (const m of priced)
+        weights[m] = (values[m] / total) * 100;
+    // Re-normalise targets over priced assets only.
+    const targetSum = priced.reduce((a, m) => a + s.targets[m], 0);
+    const targets = Object.fromEntries(priced.map((m) => [m, (s.targets[m] / targetSum) * 100]));
+    const drifted = priced.some((m) => Math.abs(weights[m] - targets[m]) > s.driftPct);
+    if (!drifted)
+        return { legs: [], warnings, weights };
+    const legs = [];
+    const deltaUsd = Object.fromEntries(priced.map((m) => [m, (targets[m] / 100) * total - values[m]])); // + = buy, − = sell
+    // Sells first (overweight non-SOL → SOL), then buys (SOL → underweight).
+    for (const m of priced) {
+        if (m === SOL_MINT)
+            continue;
+        const d = deltaUsd[m];
+        if (d < 0 && -d >= s.minTradeUsd)
+            legs.push({ inputMint: m, outputMint: SOL_MINT, amount: round(-d / prices[m]), reason: `sell overweight ${pct(weights[m])}% → ${pct(targets[m])}%` });
+    }
+    for (const m of priced) {
+        if (m === SOL_MINT)
+            continue;
+        const d = deltaUsd[m];
+        if (d > 0 && d >= s.minTradeUsd)
+            legs.push({ inputMint: SOL_MINT, outputMint: m, amount: round(d / prices[SOL_MINT]), reason: `buy underweight ${pct(weights[m])}% → ${pct(targets[m])}%` });
+    }
+    return { legs, warnings, weights };
+}
+/** TP/SL decision (P11.5). `price` undefined = no decision. Returns the updated high-water mark too. */
+export function tpslDecision(s, price) {
+    if (price === undefined || !(price > 0))
+        return { trigger: null, highWater: s.highWater };
+    const highWater = Math.max(s.highWater, price);
+    if (s.takeProfitPct !== undefined) {
+        const t = s.entryPrice * (1 + s.takeProfitPct / 100);
+        if (price >= t)
+            return { trigger: { trigger: 'take-profit', threshold: t }, highWater };
+    }
+    if (s.trailingPct !== undefined) {
+        const t = highWater * (1 - s.trailingPct / 100);
+        if (price <= t && highWater > s.entryPrice)
+            return { trigger: { trigger: 'trailing-stop', threshold: t }, highWater };
+    }
+    if (s.stopLossPct !== undefined) {
+        const t = s.entryPrice * (1 - s.stopLossPct / 100);
+        if (price <= t)
+            return { trigger: { trigger: 'stop-loss', threshold: t }, highWater };
+    }
+    return { trigger: null, highWater };
+}
+/** SOL-equivalent spent by all strategies in the UTC day containing `now` (P11.6). */
+export function solSpentToday(runs, now) {
+    const dayStart = new Date(now);
+    dayStart.setUTCHours(0, 0, 0, 0);
+    return runs.filter((r) => r.outcome === 'ok' && Date.parse(r.at) >= dayStart.getTime()).reduce((a, r) => a + (r.solEquivalent ?? 0), 0);
+}
+export function dcaLegFor(s) {
+    return { inputMint: s.inputMint, outputMint: s.outputMint, amount: s.amountPerRun, reason: `DCA run ${s.runsDone + 1}${s.totalRuns ? `/${s.totalRuns}` : ''}` };
+}
+export const MAX_CONSECUTIVE_FAILURES = 3;
+const round = (n) => Math.floor(n * 1e9) / 1e9;
+const pct = (n) => n.toFixed(1);
+export function newId(prefix, now = Date.now()) {
+    return `${prefix}_${now.toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+}

package/dist/strategies/lock.d.ts

@@ -0,0 +1,7 @@
+export interface Lock {
+    acquired: boolean;
+    ownerPid: number | null;
+    release(): void;
+}
+export declare function pidAlive(pid: number, kill?: (pid: number, sig: 0) => void): boolean;
+export declare function acquireLock(dir: string, pid?: number, alive?: (pid: number) => boolean): Lock;

package/dist/strategies/lock.js

@@ -0,0 +1,30 @@
+// PRD P11.11/P11.12 — one scheduler per state directory. The lock is a file holding the owner PID;
+// a lock whose PID is no longer alive is stale and may be reclaimed.
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function pidAlive(pid, kill = process.kill) {
+    try {
+        kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+export function acquireLock(dir, pid = process.pid, alive = pidAlive) {
+    const file = join(dir, 'scheduler.lock');
+    if (existsSync(file)) {
+        const owner = Number(readFileSync(file, 'utf8').trim());
+        if (owner && owner !== pid && alive(owner))
+            return { acquired: false, ownerPid: owner, release() { } };
+    }
+    writeFileSync(file, String(pid));
+    return {
+        acquired: true, ownerPid: pid,
+        release() { try {
+            if (Number(readFileSync(file, 'utf8').trim()) === pid)
+                unlinkSync(file);
+        }
+        catch { /* already gone */ } },
+    };
+}