@parabolicfamily/mcp 0.1.0

package/dist/tx.js

@@ -0,0 +1,105 @@
+import { encodeAbiParameters, encodeFunctionData, erc20Abi, formatUnits, keccak256, parseAbi, toHex } from "viem";
+import { curveAbi, factoryAbi, memoRouterAbi } from "./abi.js";
+import { USDC_VIEW } from "./config.js";
+const tx = (to, data, value, chainId, description) => ({
+    to,
+    data,
+    value: toHex(value),
+    valueWei: value.toString(),
+    chainId,
+    description,
+});
+/** `curve.buy(quoteIn, minTokensOut, recipient)`; native-quoted curves take the quote as msg.value, ERC-20 pairs pull it via allowance. */
+export function encodeBuy(curve, quoteIn, minTokensOut, recipient, native, chainId) {
+    const data = encodeFunctionData({ abi: curveAbi, functionName: "buy", args: [quoteIn, minTokensOut, recipient] });
+    return tx(curve, data, native ? quoteIn : 0n, chainId, `ParabolicBondingCurve.buy(quoteIn=${quoteIn}, minTokensOut=${minTokensOut}, recipient=${recipient})`);
+}
+/** `curve.sell(tokensIn, minQuoteOut, recipient)`; the curve pulls the tokens, so it needs an allowance first. */
+export function encodeSell(curve, tokensIn, minQuoteOut, recipient, chainId) {
+    const data = encodeFunctionData({ abi: curveAbi, functionName: "sell", args: [tokensIn, minQuoteOut, recipient] });
+    return tx(curve, data, 0n, chainId, `ParabolicBondingCurve.sell(tokensIn=${tokensIn}, minQuoteOut=${minQuoteOut}, recipient=${recipient})`);
+}
+/** ERC-20 `approve(spender, amount)`. */
+export function encodeApprove(token, spender, amount, chainId, what = "token") {
+    const data = encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [spender, amount] });
+    return tx(token, data, 0n, chainId, `approve ${what}: ${spender} may spend ${amount} (skip if the allowance already covers it)`);
+}
+/**
+ * `factory.launchToken(params, launchConfigId, pairToken)` with the launch fee as msg.value.
+ *
+ * There is no exemption-list overload. It was deleted from the factory on 11 September 2026: only the creator's own
+ * address is exempt from the snipe tax, which is what "no bundles, ever" means on the site.
+ */
+export function encodeLaunch(factory, params, launchConfigId, pairToken, launchFee, chainId) {
+    const data = encodeFunctionData({ abi: factoryAbi, functionName: "launchToken", args: [params, launchConfigId, pairToken] });
+    return tx(factory, data, launchFee, chainId, `ParabolicLaunchFactory.launchToken(${params.symbol}, launchConfigId=${launchConfigId}, pairToken=${pairToken}) with launch fee ${formatUnits(launchFee, 18)} USDC as value`);
+}
+/**
+ * Fair launch through ParabolicMemoRouter, called directly (any wallet; the memo-wrapped form is EOA-only and cannot
+ * carry value). Native quote: `launchAndBuy` with msg.value = launchFee + buyQuoteIn. ERC-20 quote:
+ * `launchAndBuyWithToken` with msg.value = launchFee and buyQuoteIn pulled from the caller after an approval of the
+ * router. The router forwards the caller as deployer (factory.launchTokenFor) and places the opening buy through
+ * curve.buyFor(caller, …), so it is snipe-tax exempt; it forwards no exemption list and requires
+ * params.creatorFeeRecipient to be zero or the caller (FeeRecipientMustBeCreator).
+ */
+export function encodeLaunchAndBuy(router, params, launchConfigId, pairToken, buyQuoteIn, minTokensOut, launchFee, native, chainId) {
+    if (buyQuoteIn <= 0n)
+        throw new Error("buyQuoteIn must be positive (the router reverts with ZeroBuyAmount)");
+    const functionName = native ? "launchAndBuy" : "launchAndBuyWithToken";
+    const data = encodeFunctionData({ abi: memoRouterAbi, functionName, args: [params, launchConfigId, pairToken, buyQuoteIn, minTokensOut] });
+    const value = native ? launchFee + buyQuoteIn : launchFee;
+    return {
+        tx: tx(router, data, value, chainId, `ParabolicMemoRouter.${functionName}(${params.symbol}, launchConfigId=${launchConfigId}, pairToken=${pairToken}, buyQuoteIn=${buyQuoteIn}, minTokensOut=${minTokensOut}) with ${native ? "launch fee + opening buy" : "launch fee"} (${formatUnits(value, 18)} USDC) as value`),
+        approval: native ? null : encodeApprove(pairToken, router, buyQuoteIn, chainId, "pair token (opening buy)"),
+    };
+}
+// ---- Memo-routed buy (Arc `Memo` system contract + ParabolicMemoRouter) -------------------------------------------
+//
+// `Memo.memo(target, data, memoId, memoData)` runs `target.call(data)` through Arc's callFrom precompile so the
+// router sees the signing EOA as msg.sender, then emits `Memo(...)` with the payload (referral code + note) that the
+// indexer attributes. Constraints inherited from Arc: EOA-only (the Memo contract's caller must be tx.origin, so a
+// smart-account or contract wallet cannot use it) and no value forwarding, so the router pulls whole 6-decimal USDC
+// units through the ERC-20 view of native USDC instead, which needs a one-time approval of the router.
+export const memoAbi = parseAbi(["function memo(address target, bytes data, bytes32 memoId, bytes memoData)"]);
+export const MEMO_VERSION = 1;
+export const MEMO_ACTION = { LAUNCH: 1, BUY: 2, SELL: 3, POST: 4 };
+export const MEMO_TOPIC = "parabolic.memo.v1";
+export const MAX_NOTE_BYTES = 280;
+export const ZERO_REFERRAL = "0x0000000000000000";
+const NATIVE_PER_USDC_UNIT = 1000000000000n;
+/** A wallet's referral code is bytes8 of its address: the first 16 hex characters after 0x. Accepts a code or a full address. */
+export function referralBytes8(codeOrAddress) {
+    if (!codeOrAddress)
+        return ZERO_REFERRAL;
+    const s = codeOrAddress.trim().replace(/^0x/i, "").toLowerCase();
+    if (/^[0-9a-f]{40}$/.test(s))
+        return `0x${s.slice(0, 16)}`;
+    if (/^[0-9a-f]{16}$/.test(s))
+        return `0x${s}`;
+    throw new Error("referral must be a 16-hex referral code or a wallet address");
+}
+export function encodeMemoPayload(action, referral, note = "") {
+    if (new TextEncoder().encode(note).length > MAX_NOTE_BYTES)
+        throw new Error(`memo note is longer than ${MAX_NOTE_BYTES} bytes`);
+    return encodeAbiParameters([{ type: "uint8" }, { type: "uint8" }, { type: "bytes8" }, { type: "string" }], [MEMO_VERSION, action, referral, note]);
+}
+/** keccak256(abi.encode("parabolic.memo.v1", action, subject)); the indexer filters Memo logs by this id. */
+export const memoIdOf = (action, subject) => keccak256(encodeAbiParameters([{ type: "string" }, { type: "uint8" }, { type: "address" }], [MEMO_TOPIC, action, subject]));
+/** Whole 6-decimal USDC units the router pulls through the ERC-20 view for `native` 18-decimal wei (rounded up). */
+export const toUsdcUnits = (native) => (native + NATIVE_PER_USDC_UNIT - 1n) / NATIVE_PER_USDC_UNIT;
+export function encodeMemoBuy(p) {
+    const inner = encodeFunctionData({ abi: memoRouterAbi, functionName: "buy", args: [p.curve, p.quoteIn, p.minTokensOut, p.recipient] });
+    const memoId = memoIdOf(MEMO_ACTION.BUY, p.curve);
+    const payload = encodeMemoPayload(MEMO_ACTION.BUY, referralBytes8(p.referral), p.note ?? "");
+    const data = encodeFunctionData({ abi: memoAbi, functionName: "memo", args: [p.router, inner, memoId, payload] });
+    const units = toUsdcUnits(p.quoteIn);
+    return {
+        tx: tx(p.arcMemo, data, 0n, p.chainId, `Arc Memo.memo -> ParabolicMemoRouter.buy(curve=${p.curve}, quoteIn=${p.quoteIn}) carrying referral ${referralBytes8(p.referral)}; EOA-only, no value (the router pulls ${units} USDC units via the ERC-20 view)`),
+        approval: encodeApprove(USDC_VIEW, p.router, units, p.chainId, "USDC (ERC-20 view)"),
+        usdcUnits: units.toString(),
+        eoaOnly: true,
+        memoId,
+        payload,
+    };
+}
+//# sourceMappingURL=tx.js.map

package/dist/tx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tx.js","sourceRoot":"","sources":["../src/tx.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@parabolicfamily/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Parabolic, the dollar-native token launchpad on Arc: discover coins, quote curve trades and build unsigned transactions. Never holds keys.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "parabolic-mcp": "dist/index.js"
+  },
+  "main": "dist/server.js",
+  "types": "dist/server.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "abi",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "sync-abis": "node scripts/sync-abis.mjs",
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "start": "node dist/index.js",
+    "smoke": "node scripts/smoke.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build && npm test && npm run smoke",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "viem": "^2.56.3",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.11"
+  },
+  "author": "Parabolic",
+  "homepage": "https://www.parabolic.family",
+  "bugs": {
+    "email": "contact@parabolic.family"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "arc",
+    "circle",
+    "usdc",
+    "launchpad",
+    "bonding-curve",
+    "defi",
+    "uniswap-v4",
+    "erc-8004",
+    "agent",
+    "web3"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/abi.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Abi } from "viem";
+
+/**
+ * ABI loader. `scripts/sync-abis.mjs` copies the `abi` field of the Foundry artifacts in
+ * ../contracts/out into mcp/abi/*.json; this module reads them at import time. The directory is
+ * one level above both src/ (tests) and dist/ (build), so the same relative path works for both.
+ * Override with PARABOLIC_ABI_DIR when the package is bundled elsewhere.
+ */
+export const ABI_DIR = process.env.PARABOLIC_ABI_DIR ?? resolve(dirname(fileURLToPath(import.meta.url)), "..", "abi");
+
+export const ABI_NAMES = ["ParabolicLaunchFactory", "ParabolicBondingCurve", "ParabolicLauncherToken", "ParabolicMemoRouter"] as const;
+export type AbiName = (typeof ABI_NAMES)[number];
+
+const cache = new Map<AbiName, Abi>();
+
+export function loadAbi(name: AbiName): Abi {
+  const hit = cache.get(name);
+  if (hit) return hit;
+  const file = join(ABI_DIR, `${name}.json`);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (e) {
+    throw new Error(`Cannot read the bundled ABI ${file}. The package ships abi/*.json; a missing file means a damaged install, so reinstall @parabolicfamily/mcp (${(e as Error).message})`);
+  }
+  if (!Array.isArray(parsed)) throw new Error(`ABI ${file} is not a JSON array`);
+  const abi = parsed as Abi;
+  cache.set(name, abi);
+  return abi;
+}
+
+export const factoryAbi: Abi = loadAbi("ParabolicLaunchFactory");
+export const curveAbi: Abi = loadAbi("ParabolicBondingCurve");
+export const tokenAbi: Abi = loadAbi("ParabolicLauncherToken");
+export const memoRouterAbi: Abi = loadAbi("ParabolicMemoRouter");
+
+/** Names of all functions in an ABI (used to document what the factory can and cannot enumerate). */
+export const functionNames = (abi: Abi): string[] => abi.flatMap((e) => (e.type === "function" ? [e.name] : []));

package/src/chain.ts

@@ -0,0 +1,60 @@
+import { createPublicClient, defineChain, getAbiItem, http, type Abi, type AbiEvent, type Address, type Chain, type Hex } from "viem";
+import { chainName, explorerBase } from "./config.js";
+
+/** The narrow RPC surface the server needs; tests substitute an in-memory implementation. */
+export type ReadArgs = { address: Address; abi: Abi; functionName: string; args?: readonly unknown[] };
+export type LogsArgs = { address: Address; abi: Abi; eventName: string; fromBlock: bigint; toBlock?: bigint };
+export type DecodedLog = { args: Record<string, unknown>; blockNumber: bigint; transactionHash: Hex; logIndex: number };
+
+export interface Rpc {
+  read(a: ReadArgs): Promise<unknown>;
+  logs(a: LogsArgs): Promise<DecodedLog[]>;
+  blockNumber(): Promise<bigint>;
+}
+
+/** Arc chain definition for viem: native USDC with 18-decimal native accounting. */
+export function arcChain(chainId: number, rpcUrl: string): Chain {
+  const explorer = explorerBase(chainId);
+  return defineChain({
+    id: chainId,
+    name: chainName(chainId),
+    nativeCurrency: { name: "USDC", symbol: "USDC", decimals: 18 },
+    rpcUrls: { default: { http: [rpcUrl] } },
+    ...(explorer ? { blockExplorers: { default: { name: "Arcscan", url: explorer } } } : {}),
+    testnet: chainId !== 5042,
+  });
+}
+
+/** viem-backed Rpc. HTTP batching folds the many small reads of get_coin / list_coins into a few JSON-RPC requests. */
+export function viemRpc(rpcUrl: string, chainId: number): Rpc {
+  const client = createPublicClient({ chain: arcChain(chainId, rpcUrl), transport: http(rpcUrl, { batch: { batchSize: 50, wait: 5 } }) });
+  return {
+    read: (a) => client.readContract({ address: a.address, abi: a.abi, functionName: a.functionName, args: a.args ?? [] }),
+    async logs(a) {
+      const event = getAbiItem({ abi: a.abi, name: a.eventName }) as AbiEvent | undefined;
+      if (!event || event.type !== "event") throw new Error(`No event ${a.eventName} in ABI`);
+      const logs = await client.getLogs({ address: a.address, event, fromBlock: a.fromBlock, toBlock: a.toBlock ?? "latest", strict: false });
+      return logs.map((l) => ({
+        args: (l.args ?? {}) as Record<string, unknown>,
+        blockNumber: l.blockNumber ?? 0n,
+        transactionHash: (l.transactionHash ?? "0x") as Hex,
+        logIndex: l.logIndex ?? 0,
+      }));
+    },
+    blockNumber: () => client.getBlockNumber(),
+  };
+}
+
+/** Runs `fn` over `items` with at most `limit` in flight, preserving order. */
+export async function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]> {
+  const out: R[] = new Array(items.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (next < items.length) {
+      const i = next++;
+      out[i] = await fn(items[i] as T, i);
+    }
+  });
+  await Promise.all(workers);
+  return out;
+}

package/src/coins.ts

@@ -0,0 +1,118 @@
+import { formatUnits, getAddress, type Address } from "viem";
+import { NATIVE_QUOTE } from "./config.js";
+import { toNumber } from "./curve.js";
+import type { GqlCoin } from "./subgraph.js";
+
+export type StatusKey = "climbing" | "graduated";
+export const SORT_KEYS = ["trending", "new", "near_graduation", "market_cap"] as const;
+export type SortKey = (typeof SORT_KEYS)[number];
+
+export type CoinSummary = {
+  address: Address;
+  curve: Address;
+  name: string;
+  ticker: string;
+  creator: Address;
+  pair: "USDC" | "EURC";
+  pairToken: Address;
+  quoteDecimals: number;
+  status: StatusKey;
+  /** Quote raised on the curve (net of fees), whole units; for a graduated coin the threshold it crossed. */
+  raised: string;
+  raisedRaw: bigint;
+  threshold: string;
+  thresholdRaw: bigint;
+  progressPct: number;
+  /** Whole quote units per whole token. */
+  price: number;
+  marketCap: number;
+  holders?: number;
+  volume24h?: number;
+  change24h?: number;
+  tradeCount?: number;
+  createdAt?: number;
+  lastTradeAt?: number;
+  graduatedAt?: number;
+  poolId?: string;
+  logo?: string;
+  description?: string;
+  launchConfigId?: number;
+  source: "subgraph" | "chain";
+};
+
+export const isNative = (pairToken: string): boolean => pairToken.toLowerCase() === NATIVE_QUOTE;
+export const quoteDecimalsOf = (pairToken: string): number => (isNative(pairToken) ? 18 : 6);
+
+/** Curve progress in percent with three decimals, capped at 100. */
+export const progressPct = (raised: bigint, threshold: bigint): number => (threshold <= 0n ? 0 : Math.min(100, Number((raised * 100_000n) / threshold) / 1000));
+
+const dayOf = (sec: number) => Math.floor(sec / 86_400);
+
+/**
+ * 24h figures from the coin's two most recent UTC day buckets, the same derivation as web/lib/data.ts:
+ * volume = today + yesterday; change = current price against yesterday's close (or today's open).
+ */
+export function dayStats(g: GqlCoin, now: number, quoteDecimals: number): { volume24h: number; change24h: number } {
+  const today = dayOf(now);
+  const buckets = g.dayData ?? [];
+  const volume24h = buckets.filter((d) => d.day >= today - 1).reduce((sum, d) => sum + toNumber(BigInt(d.volumeQuote), quoteDecimals), 0);
+  const todayBucket = buckets.find((d) => d.day === today);
+  const yesterday = buckets.find((d) => d.day === today - 1);
+  const ref = yesterday ? Number(yesterday.closePrice) : todayBucket ? Number(todayBucket.openPrice) : 0;
+  const current = Number(g.price);
+  const change24h = ref > 0 && current > 0 ? ((current - ref) / ref) * 100 : 0;
+  return { volume24h, change24h };
+}
+
+export function summaryFromGql(g: GqlCoin, now = Math.floor(Date.now() / 1000)): CoinSummary {
+  const native = isNative(g.pairToken);
+  const quoteDecimals = native ? 18 : 6;
+  const graduated = g.status !== "CLIMBING";
+  const raisedRaw = BigInt(g.raised);
+  const thresholdRaw = BigInt(g.graduationThreshold);
+  const { volume24h, change24h } = dayStats(g, now, quoteDecimals);
+  return {
+    address: getAddress(g.id),
+    curve: getAddress(g.curve),
+    name: g.name,
+    ticker: g.symbol,
+    creator: getAddress(g.deployer),
+    pair: native ? "USDC" : "EURC",
+    pairToken: getAddress(g.pairToken),
+    quoteDecimals,
+    status: graduated ? "graduated" : "climbing",
+    raised: formatUnits(graduated ? thresholdRaw : raisedRaw, quoteDecimals),
+    raisedRaw: graduated ? thresholdRaw : raisedRaw,
+    threshold: formatUnits(thresholdRaw, quoteDecimals),
+    thresholdRaw,
+    progressPct: graduated ? 100 : progressPct(raisedRaw, thresholdRaw),
+    price: Number(g.price),
+    marketCap: Number(g.marketCap),
+    holders: Number(g.holderCount),
+    volume24h,
+    change24h,
+    tradeCount: Number(g.tradeCount),
+    createdAt: Number(g.createdAt),
+    lastTradeAt: Number(g.lastTradeAt),
+    graduatedAt: g.graduatedAt ? Number(g.graduatedAt) : undefined,
+    poolId: g.poolId ?? undefined,
+    logo: g.logo || undefined,
+    description: g.description || undefined,
+    launchConfigId: Number(g.launchConfigId),
+    source: "subgraph",
+  };
+}
+
+const cmpBig = (a: bigint, b: bigint): number => (a < b ? -1 : a > b ? 1 : 0);
+const statusRank = (c: CoinSummary): number => (c.status === "climbing" ? 0 : 1);
+
+/** Pure sort used by list_coins; `near_graduation` ranks climbing coins by progress and puts graduated ones last. */
+export function sortCoins(list: CoinSummary[], sort: SortKey): CoinSummary[] {
+  const by: Record<SortKey, (a: CoinSummary, b: CoinSummary) => number> = {
+    trending: (a, b) => (b.volume24h ?? 0) - (a.volume24h ?? 0) || (b.lastTradeAt ?? 0) - (a.lastTradeAt ?? 0) || cmpBig(b.raisedRaw, a.raisedRaw),
+    new: (a, b) => (b.createdAt ?? 0) - (a.createdAt ?? 0),
+    near_graduation: (a, b) => statusRank(a) - statusRank(b) || b.progressPct - a.progressPct || cmpBig(b.raisedRaw, a.raisedRaw),
+    market_cap: (a, b) => b.marketCap - a.marketCap,
+  };
+  return [...list].sort(by[sort]);
+}

package/src/config.ts

@@ -0,0 +1,123 @@
+import { getAddress, isAddress, type Address } from "viem";
+
+/** Arc's system `Memo` contract (CREATE2, zero salt), verified on Arc Testnet; expected to match on mainnet. */
+export const ARC_MEMO_DEFAULT: Address = "0x5294E9927c3306DcBaDb03fe70b92e01cCede505";
+/** ERC-20 view of native USDC on Arc (6 decimals, same balance as the 18-decimal native asset). */
+export const USDC_VIEW: Address = "0x3600000000000000000000000000000000000000";
+/** `address(0)` as the pair token means the curve is quoted in native USDC. */
+export const NATIVE_QUOTE: Address = "0x0000000000000000000000000000000000000000";
+
+export const DEFAULT_CHAIN_ID = 5042002;
+
+/**
+ * Deployed Parabolic addresses per chain, so the server is useful with no configuration at all.
+ * The source repository is private; these are the same addresses the site publishes at
+ * https://www.parabolic.family/docs#contracts and that are verified on Arcscan.
+ *
+ * Arc mainnet (5042) opens on 16 September 2026. Its addresses ship in the release that follows the
+ * deployment; until then a mainnet chain id resolves the RPC and nothing else, and any tool that
+ * needs the factory says so.
+ */
+export const DEPLOYMENTS: Record<number, {
+  rpcUrl: string;
+  factory?: Address;
+  memoRouter?: Address;
+  eurc?: Address;
+  /** Deployment block. The no-subgraph listing scans TokenLaunched from here; a public RPC refuses a scan from 0. */
+  startBlock?: number;
+}> = {
+  5042002: {
+    rpcUrl: "https://rpc.testnet.arc.io",
+    factory: "0xDA14d24385483c5876e0E170c6135F14Fc3BCEc3",
+    memoRouter: "0x32E6e071eA1Fe58DF86C4D3f419a8BAF2118f505",
+    eurc: "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a",
+    startBlock: 61040913,
+  },
+  5042: {
+    rpcUrl: "https://rpc.arc.io",
+  },
+};
+
+export const DEFAULT_RPC_URL = DEPLOYMENTS[DEFAULT_CHAIN_ID].rpcUrl;
+
+export type Config = {
+  /** JSON-RPC endpoint for Arc. */
+  rpcUrl: string;
+  /** 5042002 = Arc Testnet, 5042 = Arc mainnet (id unofficial until Circle publishes it). */
+  chainId: number;
+  /** ParabolicLaunchFactory. Required for on-chain coin lookups and for building launch transactions. */
+  factory?: Address;
+  /** ParabolicMemoRouter. Optional; enables the memo-routed (referral-carrying) buy variant. */
+  memoRouter?: Address;
+  /** Parabolic subgraph GraphQL endpoint. Recommended: listing, holders, volume and stats come from here. */
+  subgraphUrl?: string;
+  /** ERC-20 EURC on Arc, required only to build EURC-quoted launches. */
+  eurc?: Address;
+  /** ParabolicHook (Uniswap v4). Optional; read from `factory.memeHook()` when unset. Used to derive pool ids. */
+  hook?: Address;
+  /** Arc's Memo system contract. */
+  arcMemo: Address;
+  /** Launch config index on the factory; preset 0 is the adopted $5K / $12,500 curve. */
+  launchConfigId: bigint;
+  /** First block to scan for `TokenLaunched` logs when listing without a subgraph. */
+  factoryStartBlock: bigint;
+};
+
+/** Environment variables the server reads, with their meaning (also rendered by `parabolic.docs`). */
+export const ENV_VARS: Array<[name: string, meaning: string]> = [
+  ["PARABOLIC_RPC_URL", `Arc JSON-RPC endpoint (default ${DEFAULT_RPC_URL})`],
+  ["PARABOLIC_CHAIN_ID", `chain id (default ${DEFAULT_CHAIN_ID}, Arc Testnet)`],
+  ["PARABOLIC_FACTORY", "ParabolicLaunchFactory address (on-chain lookups, launch transactions, log-scan listing)"],
+  ["PARABOLIC_MEMO_ROUTER", "ParabolicMemoRouter address (memo-routed buys carrying a referral code; EOA-only)"],
+  ["PARABOLIC_SUBGRAPH_URL", "Parabolic subgraph endpoint (listing, holders, volume, protocol stats)"],
+  ["PARABOLIC_EURC", "ERC-20 EURC address (EURC-quoted launches only)"],
+  ["PARABOLIC_HOOK", "ParabolicHook address (optional; read from the factory when unset)"],
+  ["PARABOLIC_ARC_MEMO", `Arc Memo system contract (default ${ARC_MEMO_DEFAULT})`],
+  ["PARABOLIC_LAUNCH_CONFIG_ID", "factory launch config index (default 0)"],
+  ["PARABOLIC_FACTORY_START_BLOCK", "first block for the TokenLaunched log scan (default 0)"],
+];
+
+function addr(name: string, v: string | undefined): Address | undefined {
+  if (v === undefined || v.trim() === "") return undefined;
+  const s = v.trim();
+  if (!isAddress(s, { strict: false })) throw new Error(`${name} is not an address: ${s}`);
+  return getAddress(s);
+}
+
+function int(name: string, v: string | undefined, fallback: number): number {
+  if (v === undefined || v.trim() === "") return fallback;
+  const n = Number(v.trim());
+  if (!Number.isInteger(n) || n < 0) throw new Error(`${name} must be a non-negative integer, got ${v}`);
+  return n;
+}
+
+export function configFromEnv(env: Record<string, string | undefined> = process.env): Config {
+  // Chain id first: every other default is read off the deployment for that chain, so setting
+  // PARABOLIC_CHAIN_ID=5042 alone moves the RPC and the addresses together instead of leaving a
+  // mainnet chain id pointed at the testnet endpoint.
+  const chainId = int("PARABOLIC_CHAIN_ID", env.PARABOLIC_CHAIN_ID, DEFAULT_CHAIN_ID);
+  const known = DEPLOYMENTS[chainId];
+  return {
+    rpcUrl: env.PARABOLIC_RPC_URL?.trim() || known?.rpcUrl || DEFAULT_RPC_URL,
+    chainId,
+    factory: addr("PARABOLIC_FACTORY", env.PARABOLIC_FACTORY) ?? known?.factory,
+    memoRouter: addr("PARABOLIC_MEMO_ROUTER", env.PARABOLIC_MEMO_ROUTER) ?? known?.memoRouter,
+    subgraphUrl: env.PARABOLIC_SUBGRAPH_URL?.trim() || undefined,
+    eurc: addr("PARABOLIC_EURC", env.PARABOLIC_EURC) ?? known?.eurc,
+    hook: addr("PARABOLIC_HOOK", env.PARABOLIC_HOOK),
+    arcMemo: addr("PARABOLIC_ARC_MEMO", env.PARABOLIC_ARC_MEMO) ?? ARC_MEMO_DEFAULT,
+    launchConfigId: BigInt(int("PARABOLIC_LAUNCH_CONFIG_ID", env.PARABOLIC_LAUNCH_CONFIG_ID, 0)),
+    factoryStartBlock: BigInt(int("PARABOLIC_FACTORY_START_BLOCK", env.PARABOLIC_FACTORY_START_BLOCK, known?.startBlock ?? 0)),
+  };
+}
+
+export const chainName = (chainId: number): string => (chainId === 5042002 ? "Arc Testnet" : chainId === 5042 ? "Arc" : `chain ${chainId}`);
+
+/** Arcscan base URL for the chain, undefined where there is no explorer (Anvil). */
+export const explorerBase = (chainId: number): string | undefined =>
+  chainId === 5042002 ? "https://testnet.arcscan.app" : chainId === 5042 ? "https://arcscan.app" : undefined;
+
+export const explorerUrl = (chainId: number, kind: "address" | "tx", value: string): string | undefined => {
+  const base = explorerBase(chainId);
+  return base ? `${base}/${kind}/${value}` : undefined;
+};