@forgedevv/shared 0.0.0-stage → 0.2.0

package/dist/env.d.ts

@@ -0,0 +1,21 @@
+export declare const R2_ENV: readonly ["R2_ACCESS_KEY_ID", "R2_SECRET_ACCESS_KEY", "R2_ACCOUNT_ID", "R2_BUCKET"];
+/** Variables that may be absent. FORGE_MINT is absent before the $FORGE launch. */
+export declare const OPTIONAL_ENV: readonly ["FORGE_MINT"];
+/**
+ * apps/web. RPC_URL and SUPABASE_SERVICE_ROLE_KEY are server-only.
+ * FORGE_GATING_AMOUNT is required only when FORGE_MINT is set.
+ */
+export declare const WEB_ENV: readonly ["SOLANA_CLUSTER", "RPC_URL", "SUPABASE_URL", "SUPABASE_ANON_KEY", "SUPABASE_SERVICE_ROLE_KEY", "ANTHROPIC_API_KEY", "FORGE_MINT", "FORGE_GATING_AMOUNT", "FORGE_CASHBOX_WALLET", "JUPITER_API_KEY", "SESSION_SECRET", "SUPABASE_JWT_SECRET", "NEXT_PUBLIC_APP_URL", "NEXT_PUBLIC_SUPABASE_URL", "NEXT_PUBLIC_SUPABASE_ANON_KEY", "NEXT_PUBLIC_SOLANA_CLUSTER", "R2_ACCESS_KEY_ID", "R2_SECRET_ACCESS_KEY", "R2_ACCOUNT_ID", "R2_BUCKET"];
+/** apps/launchpad-template. RPC_URL is server-only; FORGE_* addresses are read through @forge/core. */
+export declare const TEMPLATE_ENV: readonly ["SOLANA_CLUSTER", "RPC_URL", "FORGE_MULTISIG_VAULT", "FORGE_METEORA_REFERRAL_ACCOUNT", "FORGE_PLATFORM_FEE_WALLET", "FORGE_JUPITER_REFERRAL_ACCOUNT", "JUPITER_API_KEY", "R2_ACCESS_KEY_ID", "R2_SECRET_ACCESS_KEY", "R2_ACCOUNT_ID", "R2_BUCKET"];
+/** Variables the builder does not use itself but copies into each client Vercel project. */
+export declare const BUILDER_VERCEL_INJECTED_ENV: readonly ["FORGE_MULTISIG_VAULT", "FORGE_METEORA_REFERRAL_ACCOUNT", "FORGE_PLATFORM_FEE_WALLET", "FORGE_JUPITER_REFERRAL_ACCOUNT", "JUPITER_API_KEY", "R2_ACCESS_KEY_ID", "R2_SECRET_ACCESS_KEY", "R2_ACCOUNT_ID", "R2_BUCKET"];
+/** apps/builder. ANTHROPIC_API_KEY is used by the gateway only. */
+export declare const BUILDER_ENV: readonly ["SOLANA_CLUSTER", "SUPABASE_URL", "SUPABASE_SERVICE_ROLE_KEY", "ANTHROPIC_API_KEY", "FORGE_MULTISIG_VAULT", "FORGE_METEORA_REFERRAL_ACCOUNT", "FORGE_PLATFORM_FEE_WALLET", "FORGE_JUPITER_REFERRAL_ACCOUNT", "JUPITER_API_KEY", "R2_ACCESS_KEY_ID", "R2_SECRET_ACCESS_KEY", "R2_ACCOUNT_ID", "R2_BUCKET", "GITHUB_APP_ID", "GITHUB_APP_PRIVATE_KEY", "GITHUB_ORG", "VERCEL_TOKEN", "VERCEL_TEAM_ID", "SIGNER_URL", "SIGNER_HMAC_SECRET", "TELEGRAM_BOT_TOKEN", "TELEGRAM_CHAT_ID"];
+/** apps/signer. FORGE_MINT is used for the buyback (simulation mode when absent). */
+export declare const SIGNER_ENV: readonly ["SOLANA_CLUSTER", "RPC_URL", "SUPABASE_URL", "SUPABASE_SERVICE_ROLE_KEY", "FORGE_MINT", "FORGE_CASHBOX_WALLET", "FORGE_MULTISIG_VAULT", "FORGE_JUPITER_REFERRAL_ACCOUNT", "JUPITER_API_KEY", "SIGNER_URL", "SIGNER_HMAC_SECRET", "SIGNER_KEYSTORE_PASSPHRASE", "SIGNER_KEYSTORE_DIR", "SIGNER_ALLOWED_IPS", "SIGNER_PORT", "TELEGRAM_BOT_TOKEN", "TELEGRAM_CHAT_ID"];
+export type WebEnvName = (typeof WEB_ENV)[number];
+export type TemplateEnvName = (typeof TEMPLATE_ENV)[number];
+export type BuilderEnvName = (typeof BUILDER_ENV)[number];
+export type SignerEnvName = (typeof SIGNER_ENV)[number];
+export type EnvName = WebEnvName | TemplateEnvName | BuilderEnvName | SignerEnvName;

package/dist/env.js

@@ -0,0 +1,92 @@
+/*
+ * Environment variable names per app (docs/INTERFACES.md §8). Names only, never values.
+ * `R2_*` is expanded to the variables of the fun-launch scaffold (docs/METEORA.md).
+ */
+export const R2_ENV = [
+    'R2_ACCESS_KEY_ID',
+    'R2_SECRET_ACCESS_KEY',
+    'R2_ACCOUNT_ID',
+    'R2_BUCKET',
+];
+/** Variables that may be absent. FORGE_MINT is absent before the $FORGE launch. */
+export const OPTIONAL_ENV = ['FORGE_MINT'];
+/**
+ * apps/web. RPC_URL and SUPABASE_SERVICE_ROLE_KEY are server-only.
+ * FORGE_GATING_AMOUNT is required only when FORGE_MINT is set.
+ */
+export const WEB_ENV = [
+    'SOLANA_CLUSTER',
+    'RPC_URL',
+    'SUPABASE_URL',
+    'SUPABASE_ANON_KEY',
+    'SUPABASE_SERVICE_ROLE_KEY',
+    'ANTHROPIC_API_KEY',
+    'FORGE_MINT',
+    'FORGE_GATING_AMOUNT',
+    'FORGE_CASHBOX_WALLET',
+    'JUPITER_API_KEY',
+    'SESSION_SECRET',
+    'SUPABASE_JWT_SECRET',
+    'NEXT_PUBLIC_APP_URL',
+    'NEXT_PUBLIC_SUPABASE_URL',
+    'NEXT_PUBLIC_SUPABASE_ANON_KEY',
+    'NEXT_PUBLIC_SOLANA_CLUSTER',
+    ...R2_ENV,
+];
+/** apps/launchpad-template. RPC_URL is server-only; FORGE_* addresses are read through @forge/core. */
+export const TEMPLATE_ENV = [
+    'SOLANA_CLUSTER',
+    'RPC_URL',
+    'FORGE_MULTISIG_VAULT',
+    'FORGE_METEORA_REFERRAL_ACCOUNT',
+    'FORGE_PLATFORM_FEE_WALLET',
+    'FORGE_JUPITER_REFERRAL_ACCOUNT',
+    'JUPITER_API_KEY',
+    ...R2_ENV,
+];
+/** Variables the builder does not use itself but copies into each client Vercel project. */
+export const BUILDER_VERCEL_INJECTED_ENV = [
+    'FORGE_MULTISIG_VAULT',
+    'FORGE_METEORA_REFERRAL_ACCOUNT',
+    'FORGE_PLATFORM_FEE_WALLET',
+    'FORGE_JUPITER_REFERRAL_ACCOUNT',
+    'JUPITER_API_KEY',
+    ...R2_ENV,
+];
+/** apps/builder. ANTHROPIC_API_KEY is used by the gateway only. */
+export const BUILDER_ENV = [
+    'SOLANA_CLUSTER',
+    'SUPABASE_URL',
+    'SUPABASE_SERVICE_ROLE_KEY',
+    'ANTHROPIC_API_KEY',
+    ...BUILDER_VERCEL_INJECTED_ENV,
+    'GITHUB_APP_ID',
+    'GITHUB_APP_PRIVATE_KEY',
+    'GITHUB_ORG',
+    'VERCEL_TOKEN',
+    'VERCEL_TEAM_ID',
+    'SIGNER_URL',
+    'SIGNER_HMAC_SECRET',
+    'TELEGRAM_BOT_TOKEN',
+    'TELEGRAM_CHAT_ID',
+];
+/** apps/signer. FORGE_MINT is used for the buyback (simulation mode when absent). */
+export const SIGNER_ENV = [
+    'SOLANA_CLUSTER',
+    'RPC_URL',
+    'SUPABASE_URL',
+    'SUPABASE_SERVICE_ROLE_KEY',
+    'FORGE_MINT',
+    'FORGE_CASHBOX_WALLET',
+    'FORGE_MULTISIG_VAULT',
+    'FORGE_JUPITER_REFERRAL_ACCOUNT',
+    'JUPITER_API_KEY',
+    'SIGNER_URL',
+    'SIGNER_HMAC_SECRET',
+    'SIGNER_KEYSTORE_PASSPHRASE',
+    'SIGNER_KEYSTORE_DIR',
+    'SIGNER_ALLOWED_IPS',
+    'SIGNER_PORT',
+    'TELEGRAM_BOT_TOKEN',
+    'TELEGRAM_CHAT_ID',
+];

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './constants.js';
+export * from './spec.js';
+export * from './site-config.js';
+export * from './jobs.js';
+export * from './db.js';
+export * from './api.js';
+export * from './web-client.js';
+export * from './env.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './constants.js';
+export * from './spec.js';
+export * from './site-config.js';
+export * from './jobs.js';
+export * from './db.js';
+export * from './api.js';
+export * from './web-client.js';
+export * from './env.js';

package/dist/jobs.d.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+/** Job statuses (docs/INTERFACES.md §4). */
+export declare const JobStatus: z.ZodEnum<{
+    spec_ready: "spec_ready";
+    paid: "paid";
+    building: "building";
+    preview_ready: "preview_ready";
+    approved: "approved";
+    onchain_setup: "onchain_setup";
+    awaiting_owner_signature: "awaiting_owner_signature";
+    owner_signed: "owner_signed";
+    deploying: "deploying";
+    live: "live";
+    failed: "failed";
+    refunded: "refunded";
+}>;
+export type JobStatus = z.infer<typeof JobStatus>;
+export declare const JobType: z.ZodEnum<{
+    create_launchpad: "create_launchpad";
+    modify_launchpad: "modify_launchpad";
+}>;
+export type JobType = z.infer<typeof JobType>;
+export declare const FailedStage: z.ZodEnum<{
+    build: "build";
+    onchain: "onchain";
+    deploy: "deploy";
+}>;
+export type FailedStage = z.infer<typeof FailedStage>;
+/** Statuses during which the builder holds the job lock (locked_by / locked_at). */
+export declare const ACTIVE_JOB_STATUSES: readonly ["building", "onchain_setup", "deploying"];
+export type ActiveJobStatus = (typeof ACTIVE_JOB_STATUSES)[number];
+/** Happy path of a `create_launchpad` job, in order. */
+export declare const CREATE_FLOW: readonly ["spec_ready", "paid", "building", "preview_ready", "approved", "onchain_setup", "awaiting_owner_signature", "owner_signed", "deploying", "live"];
+/** Happy path of a `modify_launchpad` job, in order. */
+export declare const MODIFY_FLOW: readonly ["spec_ready", "paid", "building", "preview_ready", "approved", "deploying", "live"];
+export declare function isActiveJobStatus(status: JobStatus): status is ActiveJobStatus;
+/** Ordered happy path for a job type. */
+export declare function flowForJobType(type: JobType): readonly JobStatus[];
+/**
+ * Stage recorded in failed_stage when a job fails (or is found stale) in the given status:
+ * building -> build, onchain_setup -> onchain, deploying -> deploy. Null for non-active statuses.
+ */
+export declare function failedStageForStatus(status: ActiveJobStatus): FailedStage;
+export declare function failedStageForStatus(status: JobStatus): FailedStage | null;

package/dist/jobs.js

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+/** Job statuses (docs/INTERFACES.md §4). */
+export const JobStatus = z.enum([
+    /** Created by apps/web: spec confirmed (creation) or modification request recorded. */
+    'spec_ready',
+    /** Payment confirmed on-chain. */
+    'paid',
+    /** Builder: container running. */
+    'building',
+    /** Preview URL available. */
+    'preview_ready',
+    /** The client approved the preview. */
+    'approved',
+    /** Builder + signer: configs creation and launch transaction preparation. */
+    'onchain_setup',
+    /** Launch transaction ready in jobs.owner_tx; the client must sign the first buy. */
+    'awaiting_owner_signature',
+    /** apps/web: client transaction confirmed on-chain. */
+    'owner_signed',
+    /** Builder: merge to main, Vercel production deploy. */
+    'deploying',
+    'live',
+    /** A stage failed (see failed_stage and attempts). */
+    'failed',
+    'refunded',
+]);
+export const JobType = z.enum(['create_launchpad', 'modify_launchpad']);
+export const FailedStage = z.enum(['build', 'onchain', 'deploy']);
+/** Statuses during which the builder holds the job lock (locked_by / locked_at). */
+export const ACTIVE_JOB_STATUSES = [
+    'building',
+    'onchain_setup',
+    'deploying',
+];
+/** Happy path of a `create_launchpad` job, in order. */
+export const CREATE_FLOW = [
+    'spec_ready',
+    'paid',
+    'building',
+    'preview_ready',
+    'approved',
+    'onchain_setup',
+    'awaiting_owner_signature',
+    'owner_signed',
+    'deploying',
+    'live',
+];
+/** Happy path of a `modify_launchpad` job, in order. */
+export const MODIFY_FLOW = [
+    'spec_ready',
+    'paid',
+    'building',
+    'preview_ready',
+    'approved',
+    'deploying',
+    'live',
+];
+export function isActiveJobStatus(status) {
+    return ACTIVE_JOB_STATUSES.includes(status);
+}
+/** Ordered happy path for a job type. */
+export function flowForJobType(type) {
+    return type === 'create_launchpad' ? CREATE_FLOW : MODIFY_FLOW;
+}
+export function failedStageForStatus(status) {
+    switch (status) {
+        case 'building':
+            return 'build';
+        case 'onchain_setup':
+            return 'onchain';
+        case 'deploying':
+            return 'deploy';
+        default:
+            return null;
+    }
+}

package/dist/site-config.d.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+export declare const SolanaCluster: z.ZodEnum<{
+    devnet: "devnet";
+    "mainnet-beta": "mainnet-beta";
+}>;
+export type SolanaCluster = z.infer<typeof SolanaCluster>;
+/** `live`, `sleeping` (dormant) or `disabled` (cut by FORGE). Written by the builder only. */
+export declare const SiteMode: z.ZodEnum<{
+    live: "live";
+    sleeping: "sleeping";
+    disabled: "disabled";
+}>;
+export type SiteMode = z.infer<typeof SiteMode>;
+/**
+ * `forge.config.json`, generated by the builder in each client repo and read by the client site
+ * (docs/INTERFACES.md §3). The builder agent may change `theme` and `content`, never `onchain`
+ * nor `mode`. FORGE addresses (multisig, referrals, platform fee wallet) are NOT in this file.
+ */
+export declare const ForgeSiteConfig: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    name: z.ZodString;
+    slug: z.ZodString;
+    mode: z.ZodEnum<{
+        live: "live";
+        sleeping: "sleeping";
+        disabled: "disabled";
+    }>;
+    onchain: z.ZodOptional<z.ZodObject<{
+        cluster: z.ZodEnum<{
+            devnet: "devnet";
+            "mainnet-beta": "mainnet-beta";
+        }>;
+        launchpadConfig: z.ZodString;
+        launchpadCoinConfig: z.ZodString;
+        launchpadCoinMint: z.ZodString;
+        ownerWallet: z.ZodString;
+        poolCreationFeeSol: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    theme: z.ZodObject<{
+        primaryColor: z.ZodString;
+        accentColor: z.ZodString;
+        darkMode: z.ZodBoolean;
+    }, z.core.$strip>;
+    content: z.ZodObject<{
+        tagline: z.ZodString;
+        about: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ForgeSiteConfig = z.infer<typeof ForgeSiteConfig>;
+/** Read-only view of forge.config.json exposed to the template UI (docs/frontend/CONTRACT.md). */
+export interface SiteConfig {
+    name: string;
+    slug: string;
+    theme: {
+        primaryColor: string;
+        accentColor: string;
+        darkMode: boolean;
+    };
+    content: {
+        tagline: string;
+        about: string;
+    };
+    mode: SiteMode;
+}
+/** Pure projection of a parsed forge.config.json to the UI-facing SiteConfig. */
+export declare function toSiteConfig(config: ForgeSiteConfig): SiteConfig;

package/dist/site-config.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { Slug, SolanaAddress, isValidPoolCreationFeeSol } from './spec.js';
+export const SolanaCluster = z.enum(['devnet', 'mainnet-beta']);
+/** `live`, `sleeping` (dormant) or `disabled` (cut by FORGE). Written by the builder only. */
+export const SiteMode = z.enum(['live', 'sleeping', 'disabled']);
+const HexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/);
+/**
+ * `forge.config.json`, generated by the builder in each client repo and read by the client site
+ * (docs/INTERFACES.md §3). The builder agent may change `theme` and `content`, never `onchain`
+ * nor `mode`. FORGE addresses (multisig, referrals, platform fee wallet) are NOT in this file.
+ */
+export const ForgeSiteConfig = z.object({
+    version: z.literal(1),
+    name: z.string().min(2).max(32),
+    slug: Slug,
+    mode: SiteMode,
+    /** Absent until the on-chain setup is done. */
+    onchain: z
+        .object({
+        cluster: SolanaCluster,
+        launchpadConfig: SolanaAddress,
+        launchpadCoinConfig: SolanaAddress,
+        launchpadCoinMint: SolanaAddress,
+        ownerWallet: SolanaAddress,
+        /** Coin creation fee charged by this launchpad, shown to coin creators before signing. */
+        poolCreationFeeSol: z.number().refine(isValidPoolCreationFeeSol).optional(),
+    })
+        .optional(),
+    theme: z.object({
+        primaryColor: HexColor,
+        accentColor: HexColor,
+        darkMode: z.boolean(),
+    }),
+    content: z.object({
+        tagline: z.string().max(120),
+        about: z.string(),
+    }),
+});
+/** Pure projection of a parsed forge.config.json to the UI-facing SiteConfig. */
+export function toSiteConfig(config) {
+    return {
+        name: config.name,
+        slug: config.slug,
+        theme: { ...config.theme },
+        content: { ...config.content },
+        mode: config.mode,
+    };
+}

package/dist/spec.d.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+/** Base58 Solana public key (32 to 44 characters). */
+export declare const SolanaAddress: z.ZodString;
+export type SolanaAddress = z.infer<typeof SolanaAddress>;
+/** Launchpad slug: becomes `<slug>.<clients-domain>`. */
+export declare const Slug: z.ZodString;
+/** Pure check of the pool creation fee bound: 0 (when allowed) or within [min, max] SOL. */
+export declare function isValidPoolCreationFeeSol(value: number): boolean;
+/**
+ * True when a SOL amount converts exactly to lamports: finite, with at most 9 decimals (the same
+ * rule as `solToLamports` in @forge/core, which refuses anything else at build time).
+ */
+export declare function hasAtMostSolDecimals(value: number): boolean;
+/**
+ * Launchpad specification produced by the design chat, consumed by the builder and the signer
+ * (docs/INTERFACES.md §2). Bounds come from CLIENT_BOUNDS.
+ */
+export declare const LaunchpadSpec: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    ownerWallet: z.ZodString;
+    name: z.ZodString;
+    slug: z.ZodString;
+    quote: z.ZodLiteral<"SOL">;
+    tradingFeeBps: z.ZodNumber;
+    coinCreatorSharePct: z.ZodDefault<z.ZodNumber>;
+    poolCreationFeeSol: z.ZodNumber;
+    antiSniper: z.ZodDefault<z.ZodBoolean>;
+    theme: z.ZodObject<{
+        primaryColor: z.ZodString;
+        accentColor: z.ZodString;
+        darkMode: z.ZodBoolean;
+        tagline: z.ZodString;
+        logoUrl: z.ZodOptional<z.ZodURL>;
+        designNotes: z.ZodString;
+    }, z.core.$strip>;
+    launchpadCoin: z.ZodObject<{
+        name: z.ZodString;
+        symbol: z.ZodString;
+        description: z.ZodString;
+        imageUrl: z.ZodURL;
+        firstBuySol: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Parsed spec (defaults applied). */
+export type LaunchpadSpec = z.infer<typeof LaunchpadSpec>;
+/** Spec before parsing (fields with defaults are optional). */
+export type LaunchpadSpecInput = z.input<typeof LaunchpadSpec>;
+type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/** Partial spec while the chat fills it (docs/frontend/CONTRACT.md). Complete = LaunchpadSpec. */
+export type LaunchpadSpecDraft = DeepPartial<Omit<LaunchpadSpecInput, 'version' | 'quote'>> & {
+    version?: 1;
+    quote?: 'SOL';
+};
+/** Draft validation result. `errors` keys are dotted field paths, e.g. "launchpadCoin.symbol". */
+export interface SpecValidation {
+    complete: boolean;
+    errors: Record<string, string>;
+}
+/**
+ * Validates a draft against LaunchpadSpec. `version` and `quote` are fixed by the contract and
+ * filled in when missing. Keeps the first error message per field path.
+ */
+export declare function validateSpecDraft(draft: LaunchpadSpecDraft): SpecValidation;
+export {};

package/dist/spec.js

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+import { CLIENT_BOUNDS } from './constants.js';
+/** Base58 Solana public key (32 to 44 characters). */
+export const SolanaAddress = z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/, {
+    error: 'Invalid Solana address',
+});
+const HexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/, {
+    error: 'Color must be a 6-digit hex value like #7C3AED',
+});
+/** Only http(s) URLs are accepted for images and logos rendered on client sites. */
+const HttpUrl = z.url({ protocol: /^https?$/, error: 'Must be an http(s) URL' });
+/** Launchpad slug: becomes `<slug>.<clients-domain>`. */
+export const Slug = z.string().regex(/^(?=.{3,32}$)[a-z0-9](?:[a-z0-9]|-(?!-))*[a-z0-9]$/, {
+    error: 'Slug must be 3 to 32 characters: lowercase letters, digits and single dashes, not at the start or end',
+});
+/** Metaplex limits on-chain names to 32 UTF-8 bytes, not 32 characters. */
+function utf8Bytes(value) {
+    let bytes = 0;
+    for (const char of value) {
+        const code = char.codePointAt(0) ?? 0;
+        bytes += code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4;
+    }
+    return bytes;
+}
+const { tradingFeeBps, coinCreatorSharePct, poolCreationFeeSol } = CLIENT_BOUNDS;
+/** Pure check of the pool creation fee bound: 0 (when allowed) or within [min, max] SOL. */
+export function isValidPoolCreationFeeSol(value) {
+    if (value === 0)
+        return poolCreationFeeSol.allowZero;
+    return value >= poolCreationFeeSol.min && value <= poolCreationFeeSol.max;
+}
+/** Decimals of SOL: 1 SOL = 10^9 lamports. */
+const SOL_DECIMALS = 9;
+/**
+ * True when a SOL amount converts exactly to lamports: finite, with at most 9 decimals (the same
+ * rule as `solToLamports` in @forge/core, which refuses anything else at build time).
+ */
+export function hasAtMostSolDecimals(value) {
+    if (!Number.isFinite(value))
+        return false;
+    return Number(value.toFixed(SOL_DECIMALS)) === value;
+}
+const SOL_DECIMALS_ERROR = `must have at most ${SOL_DECIMALS} decimals (1 lamport)`;
+/**
+ * Launchpad specification produced by the design chat, consumed by the builder and the signer
+ * (docs/INTERFACES.md §2). Bounds come from CLIENT_BOUNDS.
+ */
+export const LaunchpadSpec = z.object({
+    version: z.literal(1),
+    /** Client wallet = session wallet = payer = feeClaimer of both configs. */
+    ownerWallet: SolanaAddress,
+    name: z.string().min(2).max(32),
+    slug: Slug,
+    quote: z.literal('SOL'),
+    tradingFeeBps: z.number().int().min(tradingFeeBps.min).max(tradingFeeBps.max),
+    coinCreatorSharePct: z
+        .number()
+        .int()
+        .min(coinCreatorSharePct.min)
+        .max(coinCreatorSharePct.max)
+        .default(coinCreatorSharePct.default),
+    poolCreationFeeSol: z
+        .number()
+        .refine(isValidPoolCreationFeeSol, {
+        error: `poolCreationFeeSol must be 0 or between ${poolCreationFeeSol.min} and ${poolCreationFeeSol.max} SOL`,
+    })
+        .refine(hasAtMostSolDecimals, { error: `poolCreationFeeSol ${SOL_DECIMALS_ERROR}` }),
+    antiSniper: z.boolean().default(true),
+    theme: z.object({
+        primaryColor: HexColor,
+        accentColor: HexColor,
+        darkMode: z.boolean(),
+        tagline: z.string().max(120),
+        logoUrl: HttpUrl.optional(),
+        /** Free-form instructions for the builder agent. */
+        designNotes: z.string().max(2000),
+    }),
+    launchpadCoin: z.object({
+        /**
+         * Written on-chain as is: no surrounding spaces (the on-chain launch refuses them), at most
+         * 32 UTF-8 bytes. Name, symbol and the metadata URI also share one byte budget in the launch
+         * transaction (`LAUNCH_METADATA_BUDGET_BYTES` in @forge/core).
+         */
+        name: z
+            .string()
+            .min(1)
+            .refine((value) => value.trim() === value, {
+            error: 'Coin name must not start or end with spaces',
+        })
+            .refine((value) => utf8Bytes(value) <= 32, { error: 'Coin name must be at most 32 bytes' }),
+        /** Written on-chain as is: the pattern leaves no room for spaces. */
+        symbol: z.string().regex(/^[A-Z0-9]{2,10}$/, {
+            error: 'Symbol must be 2 to 10 uppercase letters or digits',
+        }),
+        description: z.string().max(500),
+        imageUrl: HttpUrl,
+        /** Paid by the client. */
+        // The 10 SOL migration threshold means a first buy above ~10 SOL cannot fit in the curve.
+        firstBuySol: z
+            .number()
+            .min(0)
+            .max(10)
+            .refine(hasAtMostSolDecimals, { error: `firstBuySol ${SOL_DECIMALS_ERROR}` }),
+    }),
+});
+/**
+ * Validates a draft against LaunchpadSpec. `version` and `quote` are fixed by the contract and
+ * filled in when missing. Keeps the first error message per field path.
+ */
+export function validateSpecDraft(draft) {
+    const result = LaunchpadSpec.safeParse({ ...draft, version: 1, quote: 'SOL' });
+    if (result.success)
+        return { complete: true, errors: {} };
+    const errors = {};
+    for (const issue of result.error.issues) {
+        const key = issue.path.map(String).join('.');
+        if (!(key in errors))
+            errors[key] = issue.message;
+    }
+    return { complete: false, errors };
+}