@lightspeed-cli/speed-cli 0.1.0

package/dist/lib/swap-execute.js

@@ -0,0 +1,49 @@
+import { ethers } from "ethers";
+import { get0xQuote } from "./zerox.js";
+const ERC20_ABI = ["function approve(address spender, uint256 amount) returns (bool)"];
+/**
+ * Execute swap from an existing quote: approve if needed → send transaction → wait.
+ * Used by swap command after it has already fetched the quote for display/prechecks.
+ */
+export async function executeSwapWithQuote(signer, sellToken, quote, amountWei) {
+    if (!quote.transaction?.to) {
+        throw new Error("No transaction in quote (0x returned no fill).");
+    }
+    const data = quote.transaction.data?.trim();
+    if (!data || !data.startsWith("0x") || data.length < 10) {
+        throw new Error("Quote returned no or invalid transaction data (amount may be too small or unsupported by 0x).");
+    }
+    if (quote.issues?.allowance?.spender) {
+        const token = new ethers.Contract(sellToken, ERC20_ABI, signer);
+        const txApprove = await token.approve(quote.allowanceTarget ?? quote.issues.allowance.spender, amountWei);
+        await txApprove.wait();
+    }
+    try {
+        const tx = await signer.sendTransaction({
+            to: quote.transaction.to,
+            data,
+            value: quote.transaction.value ? BigInt(quote.transaction.value) : 0n,
+            gasLimit: quote.gas ? BigInt(quote.gas) : undefined,
+        });
+        await tx.wait();
+        return tx.hash;
+    }
+    catch (e) {
+        const err = e;
+        if (err?.code === "CALL_EXCEPTION" || (typeof err?.message === "string" && err.message.includes("revert"))) {
+            throw new Error("Transaction reverted on-chain (slippage, liquidity, or minimum amount). Try a larger amount or run again.");
+        }
+        throw e;
+    }
+}
+/**
+ * Execute one swap: get quote → approve if needed → send transaction → wait.
+ * Used by volume command. No confirmation, no dry-run.
+ * @returns { txHash, quote }
+ */
+export async function executeSwap(chainId, signer, sellToken, buyToken, amountWei) {
+    const taker = await signer.getAddress();
+    const quote = await get0xQuote(chainId, sellToken, buyToken, amountWei, taker);
+    const txHash = await executeSwapWithQuote(signer, sellToken, quote, amountWei);
+    return { txHash, quote };
+}

package/dist/lib/xp.d.ts

@@ -0,0 +1,57 @@
+declare const XP_BASE: {
+    readonly swap: 10;
+    readonly bridge: 25;
+    readonly dcaBuy: 8;
+    readonly volumeOp: 3;
+    readonly gasRefuel: 3;
+};
+export type XpActionType = keyof typeof XP_BASE;
+export interface XpStatsEntry {
+    count: number;
+    totalUSD: number;
+}
+export interface XpState {
+    totalXP: number;
+    level: number;
+    streak: number;
+    lastActivity: string;
+    stats: {
+        swaps: XpStatsEntry;
+        bridges: XpStatsEntry;
+        volumeOps: XpStatsEntry;
+        dcaBuys: XpStatsEntry;
+        gasRefuels: XpStatsEntry;
+    };
+    history: {
+        action: XpActionType;
+        xp: number;
+        usd: number;
+        at: string;
+    }[];
+}
+/** Level from total XP (1-based). */
+export declare function getLevelFromTotalXp(totalXp: number): number;
+/** XP needed to go from current level to next. */
+export declare function getXpForNextLevel(level: number): number;
+/** Progress within current level (0..1). */
+export declare function getProgressInLevel(totalXp: number): {
+    current: number;
+    needed: number;
+    fraction: number;
+};
+/**
+ * Compute XP for one action. Formula: floor(base × dollarMod(usd) × streakMult).
+ * Same usd must be used when recording to totalUSD so XP and stats stay in sync.
+ */
+export declare function computeXpForAction(action: XpActionType, usdAmount: number, streakDays: number): number;
+export declare function getTitleForLevel(level: number): string;
+export declare function loadXpState(): XpState;
+/** Reset XP to zero (level 1, no stats, no history). Persists to disk. */
+export declare function resetXpState(): void;
+/**
+ * Record one action and persist. Call after successful swap/bridge/volume op/dca buy/gas.
+ * XP is computed from the same (clamped) usd that is added to stats.totalUSD, so displayed
+ * totals and XP always reflect the same executed value per action.
+ */
+export declare function recordXpAction(action: XpActionType, usdAmount: number): number;
+export {};

package/dist/lib/xp.js

@@ -0,0 +1,217 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { getSpeedConfigDir } from "../env.js";
+const XP_BASE = {
+    swap: 10,
+    bridge: 25,
+    dcaBuy: 8,
+    volumeOp: 3,
+    gasRefuel: 3,
+};
+/** Sanitize totalUSD so obviously wrong stored values (e.g. wei as USD) don't display. */
+function sanitizeTotalUsd(totalUSD) {
+    if (typeof totalUSD !== "number" || !Number.isFinite(totalUSD) || totalUSD < 0)
+        return 0;
+    if (totalUSD > 1e12)
+        return 0; // e.g. wei or wrong scale was stored
+    return totalUSD;
+}
+const DEFAULT_STATS = () => ({
+    swaps: { count: 0, totalUSD: 0 },
+    bridges: { count: 0, totalUSD: 0 },
+    volumeOps: { count: 0, totalUSD: 0 },
+    dcaBuys: { count: 0, totalUSD: 0 },
+    gasRefuels: { count: 0, totalUSD: 0 },
+});
+const HISTORY_MAX = 100;
+function getXpPath() {
+    return join(getSpeedConfigDir(), "xp.json");
+}
+function todayISO() {
+    return new Date().toISOString().slice(0, 10);
+}
+function parseDate(s) {
+    const d = new Date(s);
+    return Number.isNaN(d.getTime()) ? new Date(0) : d;
+}
+function daysBetween(a, b) {
+    const d1 = parseDate(a).setHours(0, 0, 0, 0);
+    const d2 = parseDate(b).setHours(0, 0, 0, 0);
+    return Math.round((d2 - d1) / (24 * 60 * 60 * 1000));
+}
+/** Total XP required to reach level L (level 1 = 0 XP). */
+function totalXpForLevel(level) {
+    if (level <= 1)
+        return 0;
+    let sum = 0;
+    for (let i = 1; i < level; i++) {
+        sum += Math.floor(500 * Math.pow(i, 1.4));
+    }
+    return sum;
+}
+/** Level from total XP (1-based). */
+export function getLevelFromTotalXp(totalXp) {
+    if (totalXp <= 0)
+        return 1;
+    let level = 1;
+    while (totalXpForLevel(level + 1) <= totalXp)
+        level++;
+    return level;
+}
+/** XP needed to go from current level to next. */
+export function getXpForNextLevel(level) {
+    return Math.floor(500 * Math.pow(level, 1.4));
+}
+/** Progress within current level (0..1). */
+export function getProgressInLevel(totalXp) {
+    const level = getLevelFromTotalXp(totalXp);
+    const currentInLevel = totalXp - totalXpForLevel(level);
+    const needed = getXpForNextLevel(level);
+    return { current: currentInLevel, needed, fraction: needed > 0 ? currentInLevel / needed : 1 };
+}
+/** Dollar modifier: log10(dollars + 1), capped at 5. Min 0.15 so $0 actions give less (reduces low-value farming). */
+function dollarMod(usd) {
+    const raw = Math.log10(usd + 1);
+    const capped = Math.min(5, Math.max(0.15, raw));
+    return capped;
+}
+/** Streak multiplier: 1.0 + (streakDays * 0.02), max 1.5. */
+function streakMultiplier(streakDays) {
+    return Math.min(1.5, 1 + streakDays * 0.02);
+}
+/**
+ * Compute XP for one action. Formula: floor(base × dollarMod(usd) × streakMult).
+ * Same usd must be used when recording to totalUSD so XP and stats stay in sync.
+ */
+export function computeXpForAction(action, usdAmount, streakDays) {
+    const base = XP_BASE[action];
+    const mod = dollarMod(usdAmount);
+    const streak = streakMultiplier(streakDays);
+    return Math.floor(base * mod * streak);
+}
+/** Deterministic silly title from level (never ends). */
+const ADJECTIVES = [
+    "Speedy", "Blazing", "Cosmic", "Turbo", "Giga", "Hyper", "Ultra", "Chad", "Diamond", "Rocket",
+    "Phantom", "Ninja", "Stealth", "Smooth", "Alpha", "Sigma", "Prime", "Eternal", "Infinite", "Supreme",
+    "Mega", "Sonic", "Neo", "Cyber", "Quantum", "Atomic", "Plasma", "Crystal", "Obsidian", "Void",
+    "Storm", "Flame", "Frost", "Shadow", "Light", "Dawn", "Dusk", "Solar", "Lunar", "Stellar",
+];
+const NOUNS = [
+    "Pilot", "Runner", "Hopper", "Racer", "Surfer", "Wizard", "Ape", "Degen", "Chad", "Whale",
+    "Dragon", "Phoenix", "Titan", "Legend", "Veteran", "Sage", "Mage", "Knight", "Captain", "Lord",
+    "Grinder", "Sprint", "Bolt", "Flash", "Blur", "Ghost", "Spirit", "Core", "Soul", "Heart",
+    "Chain", "Bridge", "Swap", "Flow", "Wave", "Pulse", "Spark", "Beam", "Ray", "Edge",
+];
+export function getTitleForLevel(level) {
+    if (level < 1)
+        return "Rookie";
+    const a = (level * 7) % ADJECTIVES.length;
+    const b = (level * 11) % NOUNS.length;
+    return `${ADJECTIVES[a]} ${NOUNS[b]}`;
+}
+export function loadXpState() {
+    const path = getXpPath();
+    try {
+        if (existsSync(path)) {
+            const raw = JSON.parse(readFileSync(path, "utf-8"));
+            const stats = raw.stats;
+            const state = {
+                totalXP: Number(raw.totalXP) || 0,
+                level: Number(raw.level) || 1,
+                streak: Number(raw.streak) || 0,
+                lastActivity: typeof raw.lastActivity === "string" ? raw.lastActivity : "",
+                stats: stats
+                    ? {
+                        swaps: { count: stats.swaps?.count ?? 0, totalUSD: sanitizeTotalUsd(stats.swaps?.totalUSD ?? 0) },
+                        bridges: { count: stats.bridges?.count ?? 0, totalUSD: sanitizeTotalUsd(stats.bridges?.totalUSD ?? 0) },
+                        volumeOps: { count: stats.volumeOps?.count ?? 0, totalUSD: sanitizeTotalUsd(stats.volumeOps?.totalUSD ?? 0) },
+                        dcaBuys: { count: stats.dcaBuys?.count ?? 0, totalUSD: sanitizeTotalUsd(stats.dcaBuys?.totalUSD ?? 0) },
+                        gasRefuels: { count: stats.gasRefuels?.count ?? 0, totalUSD: sanitizeTotalUsd(stats.gasRefuels?.totalUSD ?? 0) },
+                    }
+                    : DEFAULT_STATS(),
+                history: Array.isArray(raw.history) ? raw.history.slice(-HISTORY_MAX) : [],
+            };
+            // If any totalUSD was sanitized (corrupted), persist so file is repaired
+            const hadCorruption = stats &&
+                (sanitizeTotalUsd(stats.volumeOps?.totalUSD ?? 0) !== (stats.volumeOps?.totalUSD ?? 0) ||
+                    sanitizeTotalUsd(stats.swaps?.totalUSD ?? 0) !== (stats.swaps?.totalUSD ?? 0) ||
+                    sanitizeTotalUsd(stats.bridges?.totalUSD ?? 0) !== (stats.bridges?.totalUSD ?? 0) ||
+                    sanitizeTotalUsd(stats.dcaBuys?.totalUSD ?? 0) !== (stats.dcaBuys?.totalUSD ?? 0) ||
+                    sanitizeTotalUsd(stats.gasRefuels?.totalUSD ?? 0) !== (stats.gasRefuels?.totalUSD ?? 0));
+            if (hadCorruption)
+                saveXpState(state);
+            return state;
+        }
+    }
+    catch (_) { }
+    return {
+        totalXP: 0,
+        level: 1,
+        streak: 0,
+        lastActivity: "",
+        stats: DEFAULT_STATS(),
+        history: [],
+    };
+}
+function saveXpState(state) {
+    mkdirSync(getSpeedConfigDir(), { recursive: true });
+    writeFileSync(getXpPath(), JSON.stringify(state, null, 2));
+}
+/** Reset XP to zero (level 1, no stats, no history). Persists to disk. */
+export function resetXpState() {
+    const state = {
+        totalXP: 0,
+        level: 1,
+        streak: 0,
+        lastActivity: "",
+        stats: DEFAULT_STATS(),
+        history: [],
+    };
+    saveXpState(state);
+}
+/** Clamp USD to a sane range so bad oracle/scale never corrupts totals (e.g. wei passed as USD). */
+function clampUsdForRecord(usd) {
+    if (typeof usd !== "number" || !Number.isFinite(usd) || usd < 0)
+        return 0;
+    return Math.min(usd, 1e9); // max $1B per single action
+}
+/**
+ * Record one action and persist. Call after successful swap/bridge/volume op/dca buy/gas.
+ * XP is computed from the same (clamped) usd that is added to stats.totalUSD, so displayed
+ * totals and XP always reflect the same executed value per action.
+ */
+export function recordXpAction(action, usdAmount) {
+    const state = loadXpState();
+    const today = todayISO();
+    const usd = clampUsdForRecord(usdAmount);
+    let streak = state.streak;
+    if (state.lastActivity) {
+        const days = daysBetween(state.lastActivity, today);
+        if (days === 0) {
+            // same day, keep streak
+        }
+        else if (days === 1) {
+            streak = state.streak + 1;
+        }
+        else {
+            streak = 1;
+        }
+    }
+    else {
+        streak = 1;
+    }
+    const xp = computeXpForAction(action, usd, streak);
+    state.totalXP += xp;
+    state.level = getLevelFromTotalXp(state.totalXP);
+    state.streak = streak;
+    state.lastActivity = today;
+    const statKey = action === "volumeOp" ? "volumeOps" : action === "dcaBuy" ? "dcaBuys" : action === "gasRefuel" ? "gasRefuels" : action === "swap" ? "swaps" : "bridges";
+    const entry = state.stats[statKey];
+    entry.count += 1;
+    entry.totalUSD += usd;
+    state.history.push({ action, xp, usd, at: new Date().toISOString() });
+    if (state.history.length > HISTORY_MAX)
+        state.history = state.history.slice(-HISTORY_MAX);
+    saveXpState(state);
+    return xp;
+}

package/dist/lib/zerox.d.ts

@@ -0,0 +1,25 @@
+export interface ZeroXQuoteResult {
+    sellAmount: string;
+    buyAmount: string;
+    sellToken: string;
+    buyToken: string;
+    gas?: string;
+    transaction?: {
+        to: string;
+        data: string;
+        value: string;
+        gas?: string;
+    };
+    allowanceTarget?: string;
+    issues?: {
+        allowance?: {
+            spender: string;
+        };
+        balance?: unknown;
+    };
+}
+export declare function get0xPrice(chainId: number, sellToken: string, buyToken: string, sellAmount: string, taker: string): Promise<{
+    buyAmount: string;
+    sellAmount: string;
+}>;
+export declare function get0xQuote(chainId: number, sellToken: string, buyToken: string, sellAmount: string, taker: string): Promise<ZeroXQuoteResult>;

package/dist/lib/zerox.js

@@ -0,0 +1,43 @@
+import { ZEROX_API_BASE } from "../constants.js";
+import { getEnvPath } from "../env.js";
+function get0xApiKey() {
+    const key = process.env["OX_API_KEY"] ?? process.env["0X_API_KEY"];
+    if (!key?.trim()) {
+        throw new Error(`0X_API_KEY or OX_API_KEY must be set in ${getEnvPath()}. Run 'speed setup' to configure.`);
+    }
+    return key.trim();
+}
+function getHeaders() {
+    return {
+        "0x-api-key": get0xApiKey(),
+        "0x-version": "v2",
+        "Content-Type": "application/json",
+    };
+}
+export async function get0xPrice(chainId, sellToken, buyToken, sellAmount, taker) {
+    const url = `${ZEROX_API_BASE}/swap/allowance-holder/price?chainId=${chainId}&sellToken=${sellToken}&buyToken=${buyToken}&sellAmount=${sellAmount}&taker=${taker}`;
+    const res = await fetch(url, { headers: getHeaders() });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`0x price failed: ${res.status} ${text}`);
+    }
+    const data = (await res.json());
+    return { buyAmount: data.buyAmount, sellAmount: data.sellAmount };
+}
+export async function get0xQuote(chainId, sellToken, buyToken, sellAmount, taker) {
+    const params = new URLSearchParams({
+        chainId: String(chainId),
+        sellToken,
+        buyToken,
+        sellAmount,
+        taker,
+    });
+    const url = `${ZEROX_API_BASE}/swap/allowance-holder/quote?${params}`;
+    const res = await fetch(url, { headers: getHeaders() });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`0x quote failed: ${res.status} ${text}`);
+    }
+    const data = (await res.json());
+    return data;
+}

package/dist/output.d.ts

@@ -0,0 +1,11 @@
+export declare function setJsonMode(value: boolean): void;
+export declare function isJsonMode(): boolean;
+/** Write to stdout (or JSON when --json). Human messages: use out.* or console.log. Errors: use err.* or console.error. */
+export declare function out(obj: unknown): void;
+export declare function err(message: string): void;
+export declare function success(message: string): void;
+export declare function warn(message: string): void;
+/** Suffix for errors: " Run 'speed <cmd> --help' for usage." (omit when message already includes usage). */
+export declare function usageHint(cmd: string): string;
+/** Exit with code 1; in --json mode print { error, code } to stdout, else message to stderr */
+export declare function exitWithError(message: string, code: string): never;

package/dist/output.js

@@ -0,0 +1,46 @@
+import chalk from "chalk";
+let jsonMode = false;
+export function setJsonMode(value) {
+    jsonMode = value;
+}
+export function isJsonMode() {
+    return jsonMode;
+}
+/** Write to stdout (or JSON when --json). Human messages: use out.* or console.log. Errors: use err.* or console.error. */
+export function out(obj) {
+    if (jsonMode) {
+        console.log(JSON.stringify(obj));
+    }
+    else {
+        console.log(obj);
+    }
+}
+export function err(message) {
+    if (!jsonMode) {
+        console.error(chalk.red(message));
+    }
+}
+export function success(message) {
+    if (jsonMode)
+        return;
+    console.log(chalk.green(message));
+}
+export function warn(message) {
+    if (jsonMode)
+        return;
+    console.error(chalk.yellow(message));
+}
+/** Suffix for errors: " Run 'speed <cmd> --help' for usage." (omit when message already includes usage). */
+export function usageHint(cmd) {
+    return ` Run 'speed ${cmd} --help' for usage.`;
+}
+/** Exit with code 1; in --json mode print { error, code } to stdout, else message to stderr */
+export function exitWithError(message, code) {
+    if (jsonMode) {
+        console.log(JSON.stringify({ error: message, code }));
+    }
+    else {
+        console.error(chalk.red(message));
+    }
+    process.exit(1);
+}

package/dist/rpc.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Get RPC URL for a chain: Alchemy when ALCHEMY_API_KEY is set, else one public fallback.
+ * Base (8453) can override with RPC_URL env. No health checks or caching.
+ */
+export declare function getRpcUrl(chainId: number): string;

package/dist/rpc.js

@@ -0,0 +1,22 @@
+import { ALCHEMY_CHAIN_PREFIX, PUBLIC_RPC_FALLBACKS } from "./constants.js";
+/**
+ * Get RPC URL for a chain: Alchemy when ALCHEMY_API_KEY is set, else one public fallback.
+ * Base (8453) can override with RPC_URL env. No health checks or caching.
+ */
+export function getRpcUrl(chainId) {
+    if (chainId === 8453) {
+        const custom = process.env.RPC_URL;
+        if (custom?.trim())
+            return custom.trim();
+    }
+    const apiKey = process.env.ALCHEMY_API_KEY?.trim();
+    if (apiKey) {
+        const prefix = ALCHEMY_CHAIN_PREFIX[chainId];
+        if (prefix)
+            return `https://${prefix}-mainnet.g.alchemy.com/v2/${apiKey}`;
+    }
+    const fallback = PUBLIC_RPC_FALLBACKS[chainId];
+    if (fallback)
+        return fallback;
+    throw new Error(`Unsupported chain ID: ${chainId}`);
+}

package/dist/wallet.d.ts

@@ -0,0 +1,10 @@
+import { ethers } from "ethers";
+/**
+ * Create an ethers Wallet (signer) for the given chain using PRIVATE_KEY and getRpcUrl(chainId).
+ */
+export declare function getSigner(chainId: number): ethers.Wallet;
+/**
+ * Get the address derived from PRIVATE_KEY without creating a provider.
+ */
+export declare function getAddress(): string;
+export declare function getPrivateKeyForValidation(): string;

package/dist/wallet.js

@@ -0,0 +1,28 @@
+import { ethers } from "ethers";
+import { getRpcUrl } from "./rpc.js";
+function getPrivateKey() {
+    const key = process.env.PRIVATE_KEY ?? process.env.SPEED_PRIVATE_KEY;
+    if (!key?.trim()) {
+        throw new Error("PRIVATE_KEY or SPEED_PRIVATE_KEY must be set in environment");
+    }
+    return key.startsWith("0x") ? key : `0x${key}`;
+}
+/**
+ * Create an ethers Wallet (signer) for the given chain using PRIVATE_KEY and getRpcUrl(chainId).
+ */
+export function getSigner(chainId) {
+    const key = getPrivateKey();
+    const url = getRpcUrl(chainId);
+    const provider = new ethers.JsonRpcProvider(url);
+    return new ethers.Wallet(key, provider);
+}
+/**
+ * Get the address derived from PRIVATE_KEY without creating a provider.
+ */
+export function getAddress() {
+    const key = getPrivateKey();
+    return new ethers.Wallet(key).address;
+}
+export function getPrivateKeyForValidation() {
+    return getPrivateKey();
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@lightspeed-cli/speed-cli",
+  "version": "0.1.0",
+  "description": "Speed Token CLI: swap, bridge, balance, price, volume, DCA, gas, XP. Uses 0x and Squid; config in ~/.speed.",
+  "type": "module",
+  "bin": {
+    "speed": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "speed",
+    "token",
+    "cli",
+    "swap",
+    "bridge",
+    "0x",
+    "squid",
+    "ethereum",
+    "base"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@0xsquid/sdk": "^2.2.0",
+    "@0xsquid/squid-types": "^0.1.215",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "dotenv": "^16.4.5",
+    "ethers": "^6.13.0",
+    "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.0"
+  }
+}