@potswap_io/mcp 0.1.0 → 0.3.0

package/dist/strategies/engine.js

@@ -0,0 +1,117 @@
+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}` : ''}` };
+}
+/** Limit order decision (P13.10): 'fill' when the condition holds, 'expired' past expiresAt, else null. */
+export function limitDecision(s, price, now) {
+    if (s.expiresAt && Date.parse(s.expiresAt) <= now)
+        return 'expired';
+    if (price === undefined || !(price > 0))
+        return null;
+    if (s.condition === 'below' && price <= s.triggerPriceUsd)
+        return 'fill';
+    if (s.condition === 'above' && price >= s.triggerPriceUsd)
+        return 'fill';
+    return null;
+}
+export function limitLegFor(s) {
+    return s.side === 'buy'
+        ? { inputMint: s.quoteMint, outputMint: s.mint, amount: s.amount, reason: `limit buy (${s.condition} ${s.triggerPriceUsd})` }
+        : { inputMint: s.mint, outputMint: s.quoteMint, amount: s.amount, reason: `limit sell (${s.condition} ${s.triggerPriceUsd})` };
+}
+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 */ } },
+    };
+}

package/dist/strategies/scheduler.d.ts

@@ -0,0 +1,39 @@
+import type { TradeContext } from '../trade.js';
+import type { StrategyStore } from './store.js';
+import type { Run } from './types.js';
+export interface SchedulerOptions {
+    store: StrategyStore;
+    trade: TradeContext;
+    maxDailySol: number;
+    now?: () => number;
+    tickMs?: number;
+    onRun?: (run: Run) => void;
+}
+export declare class Scheduler {
+    private store;
+    private trade;
+    private maxDailySol;
+    private now;
+    private tickMs;
+    private onRun?;
+    private timer;
+    private running;
+    /** Set while a leg executes so a stop() can wait for it (P11.11). */
+    inFlight: Promise<void> | null;
+    active: boolean;
+    constructor(o: SchedulerOptions);
+    start(): void;
+    stop(): Promise<void>;
+    /** One pass over all strategies. Safe to call concurrently; overlapping calls are skipped. */
+    tick(): Promise<void>;
+    private runTick;
+    private runDca;
+    private runRebalance;
+    private checkTpSl;
+    private checkLimit;
+    private execute;
+    private record;
+    private bumpFailure;
+    private advance;
+    private complete;
+}

package/dist/strategies/scheduler.js

@@ -0,0 +1,242 @@
+import { executeSwap } from '../trade.js';
+import { log } from '../redact.js';
+import { dcaIsComplete, dcaLegFor, isDue, limitDecision, limitLegFor, MAX_CONSECUTIVE_FAILURES, nextRunAfter, newId, rebalancePlan, solSpentToday, tpslDecision } from './engine.js';
+export class Scheduler {
+    store;
+    trade;
+    maxDailySol;
+    now;
+    tickMs;
+    onRun;
+    timer = null;
+    running = false;
+    /** Set while a leg executes so a stop() can wait for it (P11.11). */
+    inFlight = null;
+    active = false;
+    constructor(o) {
+        this.store = o.store;
+        this.trade = o.trade;
+        this.maxDailySol = o.maxDailySol;
+        this.now = o.now ?? Date.now;
+        this.tickMs = o.tickMs ?? 30_000;
+        this.onRun = o.onRun;
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.active = true;
+        this.timer = setInterval(() => { void this.tick(); }, this.tickMs);
+        void this.tick();
+    }
+    async stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        this.active = false;
+        if (this.inFlight)
+            await this.inFlight;
+    }
+    /** One pass over all strategies. Safe to call concurrently; overlapping calls are skipped. */
+    async tick() {
+        if (this.running)
+            return;
+        this.running = true;
+        const p = this.runTick().catch((e) => log('scheduler tick error', e instanceof Error ? e.message : String(e)));
+        this.inFlight = p;
+        try {
+            await p;
+        }
+        finally {
+            this.running = false;
+            this.inFlight = null;
+        }
+    }
+    async runTick() {
+        const now = this.now();
+        const state = this.store.load();
+        for (const s of state.strategies) {
+            if (s.status !== 'active')
+                continue;
+            if (s.kind === 'tpsl')
+                await this.checkTpSl(s);
+            else if (s.kind === 'limit')
+                await this.checkLimit(s);
+            else if (isDue(s, now))
+                await (s.kind === 'dca' ? this.runDca(s) : this.runRebalance(s));
+        }
+    }
+    // ---- DCA (P11.1–P11.3)
+    async runDca(s) {
+        const leg = dcaLegFor(s);
+        const out = await this.execute(s, leg);
+        this.store.update((st) => {
+            const cur = st.strategies.find((x) => x.id === s.id);
+            if (!cur || cur.status !== 'active')
+                return;
+            const now = this.now();
+            if (out.kind === 'ok' || out.kind === 'dry-run')
+                cur.runsDone++;
+            cur.nextRunAt = nextRunAfter(cur, now);
+            if (dcaIsComplete(cur)) {
+                cur.status = 'completed';
+                cur.nextRunAt = null;
+            }
+        });
+    }
+    // ---- Rebalance (P11.4)
+    async runRebalance(s) {
+        const wallet = this.trade.signer?.publicKey;
+        let balances = {}, prices = {};
+        try {
+            balances = wallet ? await this.trade.balances(wallet) : {};
+            prices = await this.trade.api.prices(Object.keys(s.targets));
+        }
+        catch (e) {
+            this.record(s, 'check', 'failed', `Could not read balances or prices: ${e instanceof Error ? e.message : String(e)}. No funds were debited.`);
+            this.bumpFailure(s.id);
+            this.advance(s.id);
+            return;
+        }
+        const plan = rebalancePlan(s, balances, prices);
+        for (const w of plan.warnings)
+            this.record(s, 'check', 'skipped', w);
+        if (plan.legs.length === 0) {
+            this.record(s, 'check', 'no-op', `Within ${s.driftPct}% of target: ${Object.entries(plan.weights).map(([m, w]) => `${short(m)} ${w.toFixed(1)}%`).join(', ')}`);
+        }
+        else {
+            for (const leg of plan.legs)
+                await this.execute(s, leg);
+        }
+        this.advance(s.id);
+    }
+    // ---- TP/SL (P11.5)
+    async checkTpSl(s) {
+        let price;
+        try {
+            price = (await this.trade.api.prices([s.mint]))[s.mint];
+        }
+        catch {
+            price = undefined;
+        }
+        if (price === undefined) {
+            this.record(s, 'check', 'skipped', 'price unavailable');
+            return;
+        }
+        const { trigger, highWater } = tpslDecision(s, price);
+        this.store.update((st) => { const cur = st.strategies.find((x) => x.id === s.id); if (cur)
+            cur.highWater = highWater; });
+        if (!trigger)
+            return;
+        const wallet = this.trade.signer?.publicKey;
+        const held = wallet ? (await this.trade.balances(wallet).catch(() => ({})))[s.mint] ?? 0 : 0;
+        const amount = Math.floor(held * (s.sellPct / 100) * 1e9) / 1e9;
+        if (amount <= 0) {
+            this.record(s, `sell ${s.sellPct}% (${trigger.trigger})`, 'completed', 'Nothing to sell; completing.');
+            this.complete(s.id);
+            return;
+        }
+        const out = await this.execute(s, { inputMint: s.mint, outputMint: s.exitMint, amount, reason: `${trigger.trigger} at ${price} (threshold ${trigger.threshold.toPrecision(6)})` });
+        if (out.kind === 'ok' || out.kind === 'dry-run')
+            this.complete(s.id);
+    }
+    // ---- Limit orders (P13.10)
+    async checkLimit(s) {
+        let price;
+        try {
+            price = (await this.trade.api.prices([s.mint]))[s.mint];
+        }
+        catch {
+            price = undefined;
+        }
+        const d = limitDecision(s, price, this.now());
+        if (d === 'expired') {
+            this.record(s, 'check', 'completed', 'Expired unfilled.');
+            this.complete(s.id);
+            return;
+        }
+        if (d !== 'fill')
+            return;
+        const out = await this.execute(s, limitLegFor(s));
+        if (out.kind === 'ok' || out.kind === 'dry-run')
+            this.complete(s.id);
+    }
+    // ---- shared leg execution with caps, run log, failure counting (P11.6–P11.8, P11.13)
+    async execute(s, leg) {
+        const now = this.now();
+        const spent = solSpentToday(this.store.load().runs, now);
+        const remainingSol = Math.max(0, this.maxDailySol - spent);
+        const out = await executeSwap(this.trade, {
+            inputMint: leg.inputMint, outputMint: leg.outputMint, amount: leg.amount, slippageBps: s.maxSlippageBps, confirm: true,
+            extraSolCap: { remainingSol, label: `Daily cap reached (${this.maxDailySol} SOL). Next legs resume at 00:00 UTC.` },
+        });
+        const action = `${leg.amount} ${short(leg.inputMint)} → ${short(leg.outputMint)} (${leg.reason})`;
+        switch (out.kind) {
+            case 'ok': {
+                const r = out.result;
+                this.record(s, action, 'ok', undefined, { signature: r.signature, inAmount: r.inAmount, inputSymbol: r.inputSymbol, outAmount: r.outAmount, outputSymbol: r.outputSymbol, feeUsd: r.feeUsd, pointsAdded: r.pointsAdded, solEquivalent: r.solEquivalent });
+                this.store.update((st) => {
+                    const cur = st.strategies.find((x) => x.id === s.id);
+                    if (!cur)
+                        return;
+                    cur.consecutiveFailures = 0;
+                    cur.totals.runs++;
+                    cur.totals.feeUsd += r.feeUsd ?? 0;
+                    cur.totals.pointsAdded += r.pointsAdded ?? 0;
+                    cur.totals.volumeUsd += out.quote.inputUsd ?? 0;
+                });
+                break;
+            }
+            case 'dry-run':
+                this.record(s, action, 'dry-run', `Would swap for ${out.quote.outAmount} ${out.quote.outputSymbol} via ${out.quote.router}`);
+                break;
+            case 'refused':
+                this.record(s, action, 'skipped', out.message);
+                break;
+            case 'quote-only':
+                this.record(s, action, 'skipped', 'internal: confirm missing');
+                break;
+            case 'no-wallet':
+                this.record(s, action, 'failed', out.message);
+                this.bumpFailure(s.id);
+                break;
+            case 'failed':
+                this.record(s, action, 'failed', out.message, { signature: out.signature });
+                this.bumpFailure(s.id);
+                break;
+        }
+        return out;
+    }
+    record(s, action, outcome, message, extra = {}) {
+        const run = { id: newId('run', this.now()), strategyId: s.id, at: new Date(this.now()).toISOString(), action, outcome, message, ...extra };
+        this.store.update((st) => { st.runs.push(run); });
+        this.onRun?.(run);
+        log(`[${s.kind} ${s.id}] ${outcome}: ${action}${message ? ` — ${message}` : ''}`);
+    }
+    bumpFailure(id) {
+        this.store.update((st) => {
+            const cur = st.strategies.find((x) => x.id === id);
+            if (!cur)
+                return;
+            cur.consecutiveFailures++;
+            if (cur.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+                cur.status = 'paused';
+                cur.pausedReason = `${MAX_CONSECUTIVE_FAILURES} consecutive failures; resume after checking the wallet and route.`;
+                cur.nextRunAt = null;
+            }
+        });
+    }
+    advance(id) {
+        this.store.update((st) => {
+            const cur = st.strategies.find((x) => x.id === id);
+            if (cur && cur.status === 'active' && cur.kind !== 'tpsl' && cur.kind !== 'limit')
+                cur.nextRunAt = nextRunAfter(cur, this.now());
+        });
+    }
+    complete(id) {
+        this.store.update((st) => { const cur = st.strategies.find((x) => x.id === id); if (cur) {
+            cur.status = 'completed';
+            cur.nextRunAt = null;
+        } });
+    }
+}
+const short = (m) => (m === 'So11111111111111111111111111111111111111112' ? 'SOL' : m.slice(0, 4) + '…' + m.slice(-4));

package/dist/strategies/store.d.ts

@@ -0,0 +1,26 @@
+import { type Run, type Strategy, type StrategyState } from './types.js';
+export interface StrategyStore {
+    load(): StrategyState;
+    save(state: StrategyState): void;
+    /** Convenience: read-modify-write. */
+    update<T>(fn: (state: StrategyState) => T): T;
+    readonly location: string;
+}
+export declare const MAX_RUNS_KEPT = 2000;
+export declare class MemoryStore implements StrategyStore {
+    private state;
+    location: string;
+    load(): StrategyState;
+    save(state: StrategyState): void;
+    update<T>(fn: (state: StrategyState) => T): T;
+}
+export declare class FileStore implements StrategyStore {
+    location: string;
+    constructor(dir?: string);
+    load(): StrategyState;
+    save(state: StrategyState): void;
+    update<T>(fn: (state: StrategyState) => T): T;
+}
+export declare function defaultStateDir(env?: NodeJS.ProcessEnv): string;
+export declare const findStrategy: (state: StrategyState, id: string) => Strategy | undefined;
+export declare const runsOf: (state: StrategyState, id: string, limit?: number) => Run[];

package/dist/strategies/store.js

@@ -0,0 +1,53 @@
+// PRD P11 — persistence: a JSON file with atomic writes (tmp + rename), plus an in-memory store for tests.
+import { mkdirSync, readFileSync, renameSync, writeFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { redact } from '../redact.js';
+import { EMPTY_STATE } from './types.js';
+export const MAX_RUNS_KEPT = 2000;
+export class MemoryStore {
+    state = structuredClone(EMPTY_STATE);
+    location = 'memory';
+    load() { return structuredClone(this.state); }
+    save(state) { this.state = structuredClone(trim(state)); }
+    update(fn) { const s = this.load(); const r = fn(s); this.save(s); return r; }
+}
+export class FileStore {
+    location;
+    constructor(dir = defaultStateDir()) {
+        mkdirSync(dir, { recursive: true });
+        this.location = join(dir, 'strategies.json');
+    }
+    load() {
+        if (!existsSync(this.location))
+            return structuredClone(EMPTY_STATE);
+        try {
+            const parsed = JSON.parse(readFileSync(this.location, 'utf8'));
+            if (parsed.version !== 1 || !Array.isArray(parsed.strategies))
+                return structuredClone(EMPTY_STATE);
+            parsed.runs ??= [];
+            return parsed;
+        }
+        catch {
+            return structuredClone(EMPTY_STATE);
+        }
+    }
+    save(state) {
+        // Redaction is belt and braces: nothing here should hold a key, but the file is on disk forever.
+        const body = redact(JSON.stringify(trim(state), null, 2));
+        const tmp = `${this.location}.${process.pid}.tmp`;
+        writeFileSync(tmp, body);
+        renameSync(tmp, this.location);
+    }
+    update(fn) { const s = this.load(); const r = fn(s); this.save(s); return r; }
+}
+export function defaultStateDir(env = process.env) {
+    return env.POTSWAP_STATE_DIR || join(homedir(), '.potswap');
+}
+function trim(state) {
+    if (state.runs.length > MAX_RUNS_KEPT)
+        state.runs = state.runs.slice(-MAX_RUNS_KEPT);
+    return state;
+}
+export const findStrategy = (state, id) => state.strategies.find((s) => s.id === id);
+export const runsOf = (state, id, limit = 50) => state.runs.filter((r) => r.strategyId === id).slice(-limit).reverse();

package/dist/strategies/tools.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { TradeContext } from '../trade.js';
+import { type StrategyStore } from './store.js';
+import type { Scheduler } from './scheduler.js';
+export interface StrategyDeps {
+    trade: TradeContext;
+    store?: StrategyStore;
+    scheduler?: Scheduler;
+}
+export declare function registerStrategyTools(server: McpServer, deps: StrategyDeps): void;