@parabolicfamily/mcp 0.1.0

package/src/server.ts

@@ -0,0 +1,229 @@
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { Rpc } from "./chain.js";
+import { SORT_KEYS } from "./coins.js";
+import { configFromEnv, type Config } from "./config.js";
+import { jsonText, toPlain } from "./format.js";
+import { Parabolic } from "./parabolic.js";
+import type { Fetch } from "./subgraph.js";
+import { readFileSync } from "node:fs";
+
+export { Parabolic } from "./parabolic.js";
+export { configFromEnv, type Config } from "./config.js";
+export type { Rpc } from "./chain.js";
+
+// Read from package.json so the version an MCP client sees can never drift from the published one.
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string };
+export const SERVER_INFO = { name: "parabolic", version } as const;
+
+export const TOOL_NAMES = [
+  "parabolic.list_coins",
+  "parabolic.get_coin",
+  "parabolic.quote_buy",
+  "parabolic.quote_sell",
+  "parabolic.build_buy_tx",
+  "parabolic.build_sell_tx",
+  "parabolic.build_launch_tx",
+  "parabolic.protocol_stats",
+  "parabolic.docs",
+] as const;
+
+export type ServerOptions = {
+  /** Overrides applied on top of the environment-derived config. */
+  config?: Partial<Config>;
+  /** Environment to read (defaults to process.env); pass {} in tests to ignore the real environment. */
+  env?: Record<string, string | undefined>;
+  /** RPC implementation (tests inject an in-memory one). */
+  rpc?: Rpc;
+  /** fetch used for the subgraph (tests inject a fake). */
+  fetch?: Fetch;
+};
+
+/**
+ * Tool errors are read by an agent and often pasted into a transcript, so they must not carry the RPC
+ * endpoint. viem embeds the full request URL and body in HttpRequestError.message, and a user who set
+ * PARABOLIC_RPC_URL to a keyed endpoint would have that key handed back by any failing call. Our own
+ * thrown messages pass through unchanged; anything carrying a URL is reduced to its first line with
+ * the endpoint redacted.
+ */
+export function safeMessage(e: unknown): string {
+  const raw = e instanceof Error ? e.message : String(e);
+  if (!/https?:\/\//.test(raw)) return raw;
+  const firstLine = raw.split("\n")[0].trim();
+  return `${firstLine.replace(/https?:\/\/[^\s"']+/g, "<rpc endpoint>")} (endpoint redacted; check the server log)`;
+}
+
+type ToolResult = { content: { type: "text"; text: string }[]; structuredContent?: Record<string, unknown>; isError?: boolean };
+
+async function run(fn: () => Promise<unknown>): Promise<ToolResult> {
+  try {
+    const plain = toPlain(await fn());
+    return { content: [{ type: "text", text: jsonText(plain) }], structuredContent: plain };
+  } catch (e) {
+    return { isError: true, content: [{ type: "text", text: `Error: ${safeMessage(e)}` }] };
+  }
+}
+
+const INSTRUCTIONS =
+  "Parabolic is a dollar-native token launchpad on Arc (bonding curves quoted in native USDC, graduation into a locked Uniswap v4 pool). " +
+  "Use list_coins / get_coin to discover coins, quote_buy / quote_sell for exact curve math read from chain, and build_*_tx for unsigned transactions " +
+  "({ to, data, value, chainId }) that the user's own wallet signs. This server never holds keys, never signs and never broadcasts. " +
+  "Amounts are whole units (\"25\" = 25 USDC); results carry both whole-unit and raw values. Read parabolic://docs/parameters for the adopted parameters and Arc facts.";
+
+/** Builds the MCP server without connecting a transport, so it can be served over stdio (src/index.ts) or HTTP. */
+export function createServer(opts: ServerOptions = {}): McpServer {
+  const config: Config = { ...configFromEnv(opts.env ?? process.env), ...opts.config };
+  const api = new Parabolic(config, { rpc: opts.rpc, fetch: opts.fetch });
+  const server = new McpServer(SERVER_INFO, { instructions: INSTRUCTIONS });
+
+  const address = z.string().describe("Token address (0x…). The curve address is accepted too.");
+  const whole = z.union([z.string(), z.number()]);
+  const slippageBps = z.number().int().min(0).max(9999).optional().describe("Slippage tolerance in basis points used to derive the minimum output (default 100 = 1%)");
+  const buyer = z.string().optional().describe("Wallet that will send the buy; when given, its snipe-tax exemption is checked on the curve");
+  const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true } as const;
+
+  server.registerTool(
+    "parabolic.list_coins",
+    {
+      title: "List Parabolic coins",
+      description: "Coins on Parabolic with status, raised / threshold / progress, price and market cap. From the subgraph when PARABOLIC_SUBGRAPH_URL is set (adds holders, 24h volume, 24h change), otherwise from a TokenLaunched log scan of the factory (newest 50).",
+      inputSchema: {
+        status: z.enum(["climbing", "graduated"]).optional().describe("climbing = still on the bonding curve; graduated = in its Uniswap v4 pool"),
+        sort: z.enum(SORT_KEYS).optional().describe("trending (24h volume, then last trade), new (launch time), near_graduation (curve progress, climbing first), market_cap"),
+        limit: z.number().int().min(1).max(100).optional().describe("Max coins to return (default 20)"),
+      },
+      annotations: readOnly,
+    },
+    (args) => run(() => api.listCoins(args)),
+  );
+
+  server.registerTool(
+    "parabolic.get_coin",
+    {
+      title: "Get a Parabolic coin",
+      description: "Everything about one coin, read from the factory, curve and token (plus the subgraph when configured): name, ticker, creator, curve, status/phase, raised/threshold/progress, price, market cap, holders, pool id, fee terms and split, snipe-tax window and the current snipe-tax bps.",
+      inputSchema: { address },
+      annotations: readOnly,
+    },
+    (args) => run(() => api.getCoin(args.address)),
+  );
+
+  server.registerTool(
+    "parabolic.quote_buy",
+    {
+      title: "Quote a curve buy",
+      description: "Tokens received for `quoteIn` USDC (or EURC) using the curve's exact math on live reserves: fee, creator tax and snipe tax breakdown, spot vs effective price, price impact, whether the buy graduates the coin, and a suggested minTokensOut.",
+      inputSchema: { address, quoteIn: whole.describe("Quote to spend, whole units (e.g. \"50\" = 50 USDC)"), buyer, slippageBps },
+      annotations: readOnly,
+    },
+    (args) => run(() => api.quoteBuy(args)),
+  );
+
+  server.registerTool(
+    "parabolic.quote_sell",
+    {
+      title: "Quote a curve sell",
+      description: "Quote received for `tokensIn` coins using the curve's exact math on live reserves: gross, fee and creator tax, effective price, price impact and a suggested minQuoteOut. Sells carry no snipe tax.",
+      inputSchema: { address, tokensIn: whole.describe("Coins to sell, whole tokens (e.g. \"1000000\")"), slippageBps },
+      annotations: readOnly,
+    },
+    (args) => run(() => api.quoteSell(args)),
+  );
+
+  server.registerTool(
+    "parabolic.build_buy_tx",
+    {
+      title: "Build an unsigned buy",
+      description: "Unsigned `curve.buy(quoteIn, minTokensOut, recipient)` as { to, data, value, chainId } for the caller's wallet to sign. Native-USDC curves take the quote as value; EURC curves return an approval step too. Pass `memo` for the memo-routed variant (referral code in an Arc memo; EOA-only).",
+      inputSchema: {
+        address,
+        quoteIn: whole.describe("Quote to spend, whole units"),
+        minTokensOut: whole.optional().describe("Minimum coins to receive, whole tokens; derived from the live quote and slippageBps when omitted"),
+        recipient: z.string().describe("Address that receives the coins (normally the signer)"),
+        buyer,
+        slippageBps,
+        memo: z.object({ referral: z.string().optional().describe("Referrer's 16-hex referral code or wallet address"), note: z.string().max(280).optional() }).optional().describe("Route through ParabolicMemoRouter via Arc's Memo contract (EOA-only, needs PARABOLIC_MEMO_ROUTER)"),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    },
+    (args) => run(() => api.buildBuyTx(args)),
+  );
+
+  server.registerTool(
+    "parabolic.build_sell_tx",
+    {
+      title: "Build an unsigned sell",
+      description: "Unsigned ERC-20 approval plus `curve.sell(tokensIn, minQuoteOut, recipient)` as { to, data, value, chainId } for the caller's wallet to sign.",
+      inputSchema: {
+        address,
+        tokensIn: whole.describe("Coins to sell, whole tokens"),
+        minQuoteOut: whole.optional().describe("Minimum quote to receive, whole units; derived from the live quote and slippageBps when omitted"),
+        recipient: z.string().describe("Address that receives the quote (normally the signer)"),
+        slippageBps,
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    },
+    (args) => run(() => api.buildSellTx(args)),
+  );
+
+  server.registerTool(
+    "parabolic.build_launch_tx",
+    {
+      title: "Build an unsigned launch",
+      description: "Unsigned `factory.launchToken(TokenParams, launchConfigId, pairToken)` with the launch fee as value, using the same TokenParams shape as the web Create form (expectedEconomics pinned from the factory, random salt). Optional devBuy returns the follow-up buy calldata for the creator to send once the curve address is known.",
+      inputSchema: {
+        name: z.string().min(1).max(64),
+        ticker: z.string().min(1).max(16).describe("Symbol, letters and digits"),
+        image: z.string().max(512).optional().describe("https:// or ipfs:// pointer to a square image"),
+        description: z.string().max(2048).optional(),
+        socials: z.object({ twitter: z.string().max(256).optional(), telegram: z.string().max(256).optional(), discord: z.string().max(256).optional(), website: z.string().max(256).optional(), farcaster: z.string().max(256).optional() }).optional(),
+        pair: z.enum(["USDC", "EURC"]).optional().describe("Quote asset (default USDC = native)"),
+        devBuy: whole.optional().describe("Creator's own first buy, whole quote units; returned as a second, snipe-tax-exempt transaction"),
+        creatorTaxBps: z.number().int().min(0).max(1000).optional().describe("Creator tax in basis points, 0–500 (5%) on the adopted parameters"),
+        creator: z.string().describe("Wallet that signs the launch; becomes deployer and creatorFeeRecipient"),
+        buybackEnabled: z.boolean().optional().describe("Default true"),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    },
+    (args) => run(() => api.buildLaunchTx(args)),
+  );
+
+  server.registerTool(
+    "parabolic.protocol_stats",
+    {
+      title: "Protocol stats",
+      description: "Launches, graduations, trades, volume and fees from the subgraph (with a daily series), plus the factory's live launch fee, curve preset, snipe-tax terms and contract addresses.",
+      annotations: readOnly,
+    },
+    () => run(() => api.protocolStats()),
+  );
+
+  server.registerTool(
+    "parabolic.docs",
+    {
+      title: "Parabolic docs",
+      description: "The adopted product parameters, curve mechanics, verified Arc network facts and this server's configuration, as text.",
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    () => Promise.resolve({ content: [{ type: "text" as const, text: api.docs() }] }),
+  );
+
+  server.registerResource(
+    "parameters",
+    "parabolic://docs/parameters",
+    { title: "Parabolic parameters and Arc facts", description: "Adopted parameters, curve mechanics, Arc network facts, server configuration", mimeType: "text/plain" },
+    (uri) => Promise.resolve({ contents: [{ uri: uri.href, mimeType: "text/plain", text: api.docs() }] }),
+  );
+
+  server.registerResource(
+    "coin",
+    new ResourceTemplate("parabolic://coins/{address}", { list: undefined }),
+    { title: "Parabolic coin", description: "Live coin detail (same payload as parabolic.get_coin) as JSON", mimeType: "application/json" },
+    async (uri, variables) => {
+      const a = Array.isArray(variables.address) ? variables.address[0] : variables.address;
+      return { contents: [{ uri: uri.href, mimeType: "application/json", text: jsonText(await api.getCoin(String(a))) }] };
+    },
+  );
+
+  return server;
+}

package/src/subgraph.ts

@@ -0,0 +1,61 @@
+/**
+ * Parabolic subgraph client (indexer/schema.graphql). Amounts are 18-decimal native USDC (or 6-decimal EURC)
+ * BigInt strings; `price` and `marketCap` are BigDecimal strings already scaled to whole quote units.
+ * The queries mirror web/lib/data.ts so the MCP server and the site read the same shapes.
+ */
+export type Fetch = typeof globalThis.fetch;
+
+export const COIN_FIELDS =
+  "id curve creator { id } deployer pairToken launchConfigId name symbol logo description totalSupply status createdAt createdAtBlock graduatedAt poolId positionId graduationThreshold raised tokensOnCurve price marketCap volumeQuote tradeCount buyCount sellCount holderCount feesQuote snipeTaxQuote lastTradeAt dayData(first: 2, orderBy: day, orderDirection: desc) { day volumeQuote openPrice closePrice }";
+
+export const DAYS = 7;
+
+export const queries = {
+  coins: `query Coins($first: Int!, $where: Coin_filter) { coins(first: $first, orderBy: lastTradeAt, orderDirection: desc, where: $where) { ${COIN_FIELDS} } }`,
+  coin: `query Coin($id: ID!) { coin(id: $id) { ${COIN_FIELDS} } }`,
+  coinByCurve: `query CoinByCurve($curve: Bytes!) { coins(first: 1, where: { curve: $curve }) { ${COIN_FIELDS} } }`,
+  protocol: `query Protocol { protocol(id: "parabolic") { coinsLaunched coinsGraduated tradeCount volumeQuote feesQuote updatedAt } dailyStats(first: ${DAYS}, orderBy: day, orderDirection: desc) { day coinsLaunched coinsGraduated tradeCount volumeQuote feesQuote } }`,
+} as const;
+
+export type GqlCoinDay = { day: number; volumeQuote: string; openPrice: string; closePrice: string };
+export type GqlCoinStatus = "CLIMBING" | "GRADUATED" | "SWEPT" | "RESCUED";
+export type GqlCoin = {
+  id: string; curve: string; creator: { id: string }; deployer: string; pairToken: string; launchConfigId: string; name: string; symbol: string; logo: string; description: string;
+  totalSupply: string; status: GqlCoinStatus; createdAt: string; createdAtBlock?: string; graduatedAt: string | null; poolId: string | null; positionId?: string | null;
+  graduationThreshold: string; raised: string; tokensOnCurve: string; price: string; marketCap: string; volumeQuote: string; tradeCount: string; buyCount: string; sellCount: string;
+  holderCount: string; feesQuote?: string; snipeTaxQuote?: string; lastTradeAt: string; dayData?: GqlCoinDay[];
+};
+export type GqlProtocol = { coinsLaunched: string; coinsGraduated: string; tradeCount: string; volumeQuote: string; feesQuote: string; updatedAt?: string };
+export type GqlDaily = { day: number; coinsLaunched: string; coinsGraduated: string; tradeCount: string; volumeQuote: string; feesQuote: string };
+
+export class Subgraph {
+  constructor(readonly url: string, private readonly fetchImpl: Fetch = globalThis.fetch) {}
+
+  async query<T>(query: string, variables: Record<string, unknown> = {}): Promise<T> {
+    const res = await this.fetchImpl(this.url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ query, variables }) });
+    if (!res.ok) throw new Error(`Subgraph responded ${res.status}`);
+    const json = (await res.json()) as { data?: T; errors?: { message: string }[] };
+    if (json.errors?.length) throw new Error(`Subgraph error: ${json.errors.map((e) => e.message).join("; ")}`);
+    if (!json.data) throw new Error("Subgraph returned no data");
+    return json.data;
+  }
+
+  async coins(where?: Record<string, unknown>, first = 200): Promise<GqlCoin[]> {
+    const d = await this.query<{ coins: GqlCoin[] }>(queries.coins, { first, where: where ?? null });
+    return d.coins;
+  }
+
+  async coin(address: string): Promise<GqlCoin | null> {
+    const d = await this.query<{ coin: GqlCoin | null }>(queries.coin, { id: address.toLowerCase() });
+    return d.coin;
+  }
+
+  async coinByCurve(curve: string): Promise<GqlCoin | null> {
+    const d = await this.query<{ coins: GqlCoin[] }>(queries.coinByCurve, { curve: curve.toLowerCase() });
+    return d.coins[0] ?? null;
+  }
+
+  async protocol(): Promise<{ protocol: GqlProtocol | null; dailyStats: GqlDaily[] }> {
+    return this.query(queries.protocol);
+  }
+}

package/src/tx.ts

@@ -0,0 +1,146 @@
+import { encodeAbiParameters, encodeFunctionData, erc20Abi, formatUnits, keccak256, parseAbi, toHex, type Address, type Hex } from "viem";
+import { curveAbi, factoryAbi, memoRouterAbi } from "./abi.js";
+import { USDC_VIEW } from "./config.js";
+
+/**
+ * Unsigned transaction builders. Nothing here signs or sends: the caller's wallet does. `value` is a 0x-hex quantity
+ * (what eth_sendTransaction expects); `valueWei` is the same number in decimal for convenience.
+ */
+export type UnsignedTx = {
+  to: Address;
+  data: Hex;
+  value: Hex;
+  valueWei: string;
+  chainId: number;
+  description: string;
+};
+
+const tx = (to: Address, data: Hex, value: bigint, chainId: number, description: string): UnsignedTx => ({
+  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: Address, quoteIn: bigint, minTokensOut: bigint, recipient: Address, native: boolean, chainId: number): UnsignedTx {
+  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: Address, tokensIn: bigint, minQuoteOut: bigint, recipient: Address, chainId: number): UnsignedTx {
+  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: Address, spender: Address, amount: bigint, chainId: number, what = "token"): UnsignedTx {
+  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)`);
+}
+
+export type Socials = { twitter: string; telegram: string; discord: string; website: string; farcaster: string };
+
+/** ParabolicLaunchFactory.TokenParams, the same shape web/components/CreateForm.tsx submits. */
+export type TokenParams = {
+  name: string;
+  symbol: string;
+  logo: string;
+  description: string;
+  socials: Socials;
+  creatorFeeRecipient: Address;
+  creatorTaxBps: number;
+  buybackEnabled: boolean;
+  /** factory.previewLaunchEconomics(launchConfigId, pairToken): pins the curve terms the launch expects. */
+  expectedEconomics: Hex;
+  /** Random 32 bytes; forwarded to the deployer (reserved for deterministic deployments). */
+  salt: Hex;
+};
+
+/**
+ * `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: Address, params: TokenParams, launchConfigId: bigint, pairToken: Address, launchFee: bigint, chainId: number): UnsignedTx {
+  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: Address, params: TokenParams, launchConfigId: bigint, pairToken: Address, buyQuoteIn: bigint, minTokensOut: bigint, launchFee: bigint, native: boolean, chainId: number): { tx: UnsignedTx; approval: UnsignedTx | null } {
+  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 } as const;
+export const MEMO_TOPIC = "parabolic.memo.v1";
+export const MAX_NOTE_BYTES = 280;
+export const ZERO_REFERRAL: Hex = "0x0000000000000000";
+const NATIVE_PER_USDC_UNIT = 1_000_000_000_000n;
+
+/** 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: string | undefined): Hex {
+  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: number, referral: Hex, note = ""): Hex {
+  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: number, subject: Address): Hex =>
+  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: bigint): bigint => (native + NATIVE_PER_USDC_UNIT - 1n) / NATIVE_PER_USDC_UNIT;
+
+export type MemoBuy = { tx: UnsignedTx; approval: UnsignedTx; usdcUnits: string; eoaOnly: true; memoId: Hex; payload: Hex };
+
+export function encodeMemoBuy(p: { arcMemo: Address; router: Address; curve: Address; quoteIn: bigint; minTokensOut: bigint; recipient: Address; referral?: string; note?: string; chainId: number }): MemoBuy {
+  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,
+  };
+}