@peddles/sdk 0.2.0

package/src/launch/addresses.ts

@@ -0,0 +1,58 @@
+import type { Address } from 'viem';
+import { addressOf, deploymentFor } from '../deployments.js';
+
+/**
+ * The addresses a launch builder needs, per chain. INJECTED, never assumed:
+ * every consumer resolves them from the active chain's deployment artifact —
+ * the SDK's own address book (`launchAddressesFor`) or any artifact keyed by
+ * contract name (`launchAddressesFromRecord`, what the API and the CLI use).
+ *
+ * `clogVaultFactory` is nullable and that is the point: a deployment made before
+ * the Clog launch type existed has no such contract, and a clog type is then
+ * refused rather than launched without its vault.
+ */
+export interface LaunchAddresses {
+  readonly factory: Address;
+  readonly orchestrator: Address;
+  readonly liquidityExecutor: Address;
+  readonly feeHook: Address;
+  readonly stockLaunchpad: Address;
+  readonly clogVaultFactory: Address | null;
+}
+
+const ZERO = /^0x0{40}$/i;
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+
+function required(record: Readonly<Record<string, unknown>>, name: string): Address {
+  const value = record[name];
+  if (typeof value !== 'string' || !ADDRESS.test(value) || ZERO.test(value)) {
+    throw new Error(`Launch addresses: ${name} is missing from the deployment record.`);
+  }
+  return value as Address;
+}
+
+/** From a deployment artifact keyed by contract name (`contracts/deployments/<chainId>.json`). */
+export function launchAddressesFromRecord(record: Readonly<Record<string, unknown>>): LaunchAddresses {
+  const clog = record['PeddlesClogVaultFactory'];
+  return {
+    factory: required(record, 'PeddlesFactoryV20'),
+    orchestrator: required(record, 'PeddlesLaunchOrchestratorV20'),
+    liquidityExecutor: required(record, 'PeddlesV4LiquidityExecutor'),
+    feeHook: required(record, 'PeddlesFeeHook'),
+    stockLaunchpad: required(record, 'PeddlesStockLaunchpad'),
+    clogVaultFactory: typeof clog === 'string' && ADDRESS.test(clog) && !ZERO.test(clog) ? (clog as Address) : null,
+  };
+}
+
+/** From the SDK's shipped address book. Throws `UnknownChainError` for a chain it has none for. */
+export function launchAddressesFor(chainId: number): LaunchAddresses {
+  const book = deploymentFor(chainId);
+  return {
+    factory: addressOf(chainId, 'PeddlesFactoryV20'),
+    orchestrator: addressOf(chainId, 'PeddlesLaunchOrchestratorV20'),
+    liquidityExecutor: addressOf(chainId, 'PeddlesV4LiquidityExecutor'),
+    feeHook: addressOf(chainId, 'PeddlesFeeHook'),
+    stockLaunchpad: addressOf(chainId, 'PeddlesStockLaunchpad'),
+    clogVaultFactory: launchAddressesFromRecord(book).clogVaultFactory,
+  };
+}

package/src/launch/feeTerms.ts

@@ -0,0 +1,93 @@
+/**
+ * The launch fee terms — one fee model for every launch type, chosen at launch
+ * and permanent. A pure port of the web app's `features/launch/feeTerms.ts`
+ * (the bigint slice the builders need; the render helpers stay in the web).
+ *
+ *   taxBps              the all-in tax on every trade, TAX_MIN_BPS..TAX_MAX_BPS
+ *   excessToCreatorBps  of everything ABOVE the first BASE_BPS, the fraction
+ *                       (0..10000) that goes to the creator; the rest to holders
+ *
+ * Import-free, bigint only. Nothing here is a `number`.
+ */
+
+/** 100% in basis points. */
+export const BPS = 10_000n;
+
+/** The all-in tax a launch may choose, inclusive. 1.00% .. 10.00%. */
+export const TAX_MIN_BPS = 100n;
+export const TAX_MAX_BPS = 1_000n;
+
+/** The first 1.00% of every tax, split evenly and never adjustable. */
+export const BASE_BPS = 100n;
+export const PLATFORM_BASE_BPS = 50n;
+export const CREATOR_BASE_BPS = 50n;
+
+/** `excessToCreatorBps` bounds, inclusive. */
+export const EXCESS_MIN_BPS = 0n;
+export const EXCESS_MAX_BPS = BPS;
+
+export interface FeeTerms {
+  readonly taxBps: bigint;
+  readonly excessToCreatorBps: bigint;
+}
+
+export type FeeTermsIssue =
+  | { readonly field: 'taxBps'; readonly code: 'TAX_BELOW_MIN' | 'TAX_ABOVE_MAX' }
+  | { readonly field: 'excessToCreatorBps'; readonly code: 'SPLIT_OUT_OF_RANGE' };
+
+/** The first bound a pair of terms breaks, or null when both are in range. */
+export function validateFeeTerms(terms: FeeTerms): FeeTermsIssue | null {
+  if (terms.taxBps < TAX_MIN_BPS) return { field: 'taxBps', code: 'TAX_BELOW_MIN' };
+  if (terms.taxBps > TAX_MAX_BPS) return { field: 'taxBps', code: 'TAX_ABOVE_MAX' };
+  if (terms.excessToCreatorBps < EXCESS_MIN_BPS || terms.excessToCreatorBps > EXCESS_MAX_BPS) {
+    return { field: 'excessToCreatorBps', code: 'SPLIT_OUT_OF_RANGE' };
+  }
+  return null;
+}
+
+/** Per-trade split, each leg in units of `BPS * BPS` (= 100% of volume). Exact, no rounding. */
+export interface FeeSplitRate {
+  readonly platform: bigint;
+  readonly creator: bigint;
+  readonly holders: bigint;
+  readonly total: bigint;
+}
+
+/** The exact per-trade split, or null for terms outside the bounds. */
+export function feeSplitRate(terms: FeeTerms): FeeSplitRate | null {
+  if (validateFeeTerms(terms) !== null) return null;
+  const excess = terms.taxBps - BASE_BPS;
+  const platform = PLATFORM_BASE_BPS * BPS;
+  const creator = CREATOR_BASE_BPS * BPS + excess * terms.excessToCreatorBps;
+  const holders = excess * (BPS - terms.excessToCreatorBps);
+  return { platform, creator, holders, total: platform + creator + holders };
+}
+
+const PERCENT_RE = /^(\d{1,3})(?:\.(\d{0,2}))?$/;
+
+/** "2.5" → 250n. At most two decimal places; anything else is null. Bounds are not checked. */
+export function parseTaxPercent(text: string): bigint | null {
+  const match = PERCENT_RE.exec(text.trim());
+  if (!match) return null;
+  const whole = BigInt(match[1]!);
+  const frac = BigInt((match[2] ?? '').padEnd(2, '0'));
+  return whole * 100n + frac;
+}
+
+/** 250n → "2.50". Integer bps only; the percent sign is the caller's. */
+export function formatTaxPercent(bps: bigint): string {
+  const sign = bps < 0n ? '-' : '';
+  const abs = bps < 0n ? -bps : bps;
+  return `${sign}${abs / 100n}.${(abs % 100n).toString().padStart(2, '0')}`;
+}
+
+/** A `FeeSplitRate` leg as a percent string with up to four decimals, for the render edge only. */
+export function formatRatePercent(rate: bigint): string {
+  // rate / (BPS*BPS) * 100 = rate / 1_000_000  →  four decimals of a percent.
+  const unit = BPS * BPS / 100n / 10_000n; // one 0.0001% in rate units
+  const units = rate / unit;
+  const whole = units / 10_000n;
+  let frac = (units % 10_000n).toString().padStart(4, '0');
+  while (frac.length > 2 && frac.endsWith('0')) frac = frac.slice(0, -1);
+  return `${whole}.${frac}`;
+}

package/src/launch/index.ts

@@ -0,0 +1,93 @@
+/**
+ * @peddles/sdk/launch — build a Peddles launch transaction, non-custodially.
+ *
+ * Pure builders ported from the web app's launch forms and held identical by
+ * test: the same salt miner, plan, input and call assembly the forms sign, so
+ * the REST API, the CLI, the widget and an AI agent all produce EXACTLY the bytes
+ * a creator would have signed in the app.
+ *
+ * Nothing here holds a key or sends a transaction. Every function returns data
+ * (`to`, `data`, `value`) for something else to sign. Every address, decimal,
+ * tick and fee is read from the active chain through the `PublicClient` you pass
+ * in; nothing is a constant.
+ */
+export {
+  ADDRESS_SUFFIX,
+  ZERO_SALT,
+  boundSalt,
+  create2Address,
+  hasSuffix,
+  randomSalt,
+  mineSalt,
+  MiningAbortedError,
+  MiningExhaustedError,
+} from './salt.js';
+export type { MineParams, MinedSalt } from './salt.js';
+
+export { MIN_TICK, MAX_TICK, Q96, getSqrtPriceAtTick, amountForLiquidity, liquidityForAmount, startSqrtPrice } from './tickMath.js';
+export type { LiquidityQuote } from './tickMath.js';
+
+export {
+  BPS,
+  TAX_MIN_BPS,
+  TAX_MAX_BPS,
+  BASE_BPS,
+  PLATFORM_BASE_BPS,
+  CREATOR_BASE_BPS,
+  EXCESS_MIN_BPS,
+  EXCESS_MAX_BPS,
+  validateFeeTerms,
+  feeSplitRate,
+  parseTaxPercent,
+  formatTaxPercent,
+  formatRatePercent,
+} from './feeTerms.js';
+export type { FeeTerms, FeeTermsIssue, FeeSplitRate } from './feeTerms.js';
+
+export { launchAddressesFor, launchAddressesFromRecord } from './addresses.js';
+export type { LaunchAddresses } from './addresses.js';
+
+export { VARIANT_ASSET, BPS_DENOMINATOR, resolveTerms, readLaunchVariants, variantForType } from './variants.js';
+export type { VariantAllocation, LaunchTypeShape, ResolvedTerms, LaunchVariant, LaunchTypeName } from './variants.js';
+
+export { SUPPLY_UNITS, LAUNCH_COIN_DECIMALS, buildWethLaunchPlan } from './wethPlan.js';
+export type { WethLaunchPlan, WethPlanArgs } from './wethPlan.js';
+
+export {
+  assetParamsV1Components,
+  EMPTY_WETH_METADATA,
+  buildInitCalls,
+  wethLaunchTermsIssue,
+  buildWethLaunchInput,
+  buildWethLaunchCall,
+  encodeWethLaunchCall,
+  orchestratorLaunchFeeAbi,
+  readOrchestratorLaunchFee,
+} from './wethCall.js';
+export type { WethMetadata, WethLaunchArgs, WethLaunchInput, WethLaunchCall, UnsignedLaunchTx, OrchestratorLaunchFee } from './wethCall.js';
+
+export {
+  stockLaunchTermsIssue,
+  buildStockLaunchCall,
+  encodeStockLaunchCall,
+  encodeStockApproval,
+  erc20ApprovalAbi,
+  readStockAllowance,
+  readStockLaunchFee,
+  readStockMiningInputs,
+  predictStockCoin,
+  readStockQuotes,
+  isQuoteAllowed,
+} from './stockCall.js';
+export type { StockLaunchArgs, StockLaunchCall, StockLaunchFee, StockMiningInputs, StockQuote } from './stockCall.js';
+
+export { LAUNCH_REVERT_REASONS, REVERTED_ON_CHAIN, revertDataOf, revertIdentifier, explainLaunchRevert, decodeLaunchRevert } from './revert.js';
+export type { DecodedLaunchRevert } from './revert.js';
+
+export {
+  launchOrchestratorAbi,
+  stockLaunchpadLaunchAbi,
+  liquidityExecutorLaunchAbi,
+  tokenMetadataAbi,
+  launchErrorsAbi,
+} from './abi.generated.js';

package/src/launch/revert.ts

@@ -0,0 +1,188 @@
+import { decodeErrorResult, isHex } from 'viem';
+import type { Hex } from 'viem';
+import { launchErrorsAbi } from './abi.generated.js';
+import { TAX_MAX_BPS, TAX_MIN_BPS, formatTaxPercent } from './feeTerms.js';
+
+/**
+ * Turn a launch revert into a sentence someone can act on — a port of the web
+ * app's `features/launch/txReason.ts`, minus the wallet-specific cases.
+ *
+ * Every entry maps to a real `require` string or custom error in `contracts/src/`.
+ * The table is keyed by the contract's own identifier, so a renamed error stops
+ * matching and falls through to the honest generic case. An unrecognised revert
+ * returns `raw: null` — a confident wrong reason is worse than "the contract
+ * rejected this", because the user acts on it.
+ */
+
+const TAX_MIN = formatTaxPercent(TAX_MIN_BPS);
+const TAX_MAX = formatTaxPercent(TAX_MAX_BPS);
+
+export const LAUNCH_REVERT_REASONS: Readonly<Record<string, string>> = {
+  // ---- PeddlesStockLaunchpad -------------------------------------------------
+  POOL_PRICE_MISMATCH:
+    'A Uniswap pool for this exact token address and quote already exists at a different price, so the launch cannot initialise it. Prepare again — a fresh salt moves the token to an unused address.',
+  QUOTE_NOT_ALLOWED: 'The launchpad does not allow this quote asset. Pick one from the list — anything else fails.',
+  LAUNCH_FEE_REQUIRED:
+    'The transaction did not carry the launchpad’s launch fee. The fee is read live before signing, so it changed between the quote and the signature — prepare again.',
+  NoDevBuy: 'A minimum-tokens-out was set with a dev-buy amount of zero. Either enter an amount to spend, or clear the slippage floor.',
+  NoSwapRouter: 'The launchpad has no swap router configured, so it cannot perform a dev buy. Launch without a dev buy, then buy once the pool is live.',
+  DevBuySlippage: 'The dev buy would have returned fewer tokens than your minimum. Lower the minimum-tokens-out, or reduce the amount you are spending.',
+  QuotePullFailed: 'The quote token could not be pulled from your wallet. Check the approval covers the full dev-buy amount and that your balance still holds it.',
+  QuoteApproveFailed: 'The launchpad could not approve the swap router to spend the quote asset. Try a smaller dev buy or launch without one.',
+  QuoteRefundFailed: 'The unspent part of the dev buy could not be returned. Nothing was launched.',
+  TICK_RANGE: 'The opening price configured for this quote asset is outside the range a pool can hold.',
+  TickRange: 'The opening price configured for this quote asset is outside the range a pool can hold.',
+  TickLow: 'The opening price configured for this quote asset is outside the range a pool can hold.',
+  TickHigh: 'The opening price configured for this quote asset is outside the range a pool can hold.',
+  TICK_SPACING: 'The opening price configured for this quote asset is not one this pool can open at.',
+  ZERO_QUOTE: 'No quote asset was selected.',
+  POOL_INIT_FAILED: 'The pool could not be opened with these settings.',
+  HolderRewardsBinding: 'The token’s holder rewards could not be connected during the launch, so nothing launched.',
+  ZERO_FEE_HOOK: 'The launchpad has no fee hook, so it cannot open a pool. Nothing launched.',
+  UNKNOWN_COIN: 'This token was not launched through this launchpad.',
+
+  // ---- Launched tokens ------------------------------------------------------
+  NotifyGasTooLow: 'The transaction ran out of gas for this token’s reward update, so nothing moved. Try again and let your wallet estimate the gas.',
+
+  // ---- PeddlesFeeHook ---------------------------------------------------------
+  FeeBelowFloor: `The trading fee is below the ${TAX_MIN}% minimum. Choose a fee between ${TAX_MIN}% and ${TAX_MAX}%.`,
+  FeeAboveCap: `The trading fee is above the ${TAX_MAX}% maximum, or the split is outside all to holders and all to you. Choose a fee between ${TAX_MIN}% and ${TAX_MAX}%.`,
+  AlreadyRegistered: 'A pool for this token and quote is already set up, so this launch cannot open it.',
+  NotRegistered: 'This pool has no Peddles trading fee set up.',
+
+  // ---- PeddlesV4SwapRouter ------------------------------------------------------
+  FeeStackingForbidden: 'This pool already charges its trading fee, so the router refuses to add a second fee on top.',
+  Slippage: 'The buy would return fewer tokens than your minimum, so it would fail. Lower the minimum or the amount.',
+
+  // ---- PeddlesLaunchOrchestratorV20 (WETH path) ------------------------------
+  UNSUPPORTED_VARIANT: 'Peddles does not support this kind of token on this network.',
+  CREATOR_MISMATCH: 'The launch was built for a different creator address than the wallet that signed it. Prepare it again for the signing wallet.',
+  BAD_FACTORY_VALUE: 'The transaction carried less value than the launch declared.',
+  BAD_DEV_BUY_VALUE: 'The transaction carried less value than the first buy. Nothing launched.',
+  NO_DEV_BUY: 'A minimum was set with no first buy. Enter an amount to spend, or clear the minimum.',
+  NO_SWAP_ROUTER: 'The launch has no swap router to make the first buy through. Launch without a first buy, then buy once the pool is live.',
+  DEV_BUY_SLIPPAGE: 'The first buy would return fewer tokens than your minimum, so nothing launched. Lower the minimum or the amount.',
+  SUPPLY_MUST_BE_ONE_BILLION: 'Every Peddles launch is exactly 1,000,000,000 tokens. The supply this launch declared does not match.',
+  BPS_SUM: 'The allocation legs do not sum to 100%.',
+  NO_LAUNCH_BURN: 'Peddles refuses any launch that burns supply.',
+  BAD_LIQUIDITY_INPUT: 'The pool settings this launch worked out were rejected. Prepare again so they are recalculated from the current on-chain configuration.',
+  BAD_POOL_PARAMS: 'The pool price or liquidity did not match what the launch expects. Prepare again to recalculate them.',
+  TOKEN_PREDICTION_MISMATCH: 'The token did not deploy at the address Peddles previewed. Nothing launched; prepare again with a fresh salt.',
+  CLOG_NOT_ON_GRADUATION: 'A collection cannot launch a coin that holds supply back.',
+
+  // ---- PeddlesClogVault ---------------------------------------------------------
+  FloorUnset: 'The creator has not set a minimum price, so only the creator can sell the next slice.',
+  TooSoon: 'The next slice cannot be sold yet. Try again once the interval has passed.',
+  NotCreator: 'Only this coin’s creator can do this.',
+
+  // ---- shared ---------------------------------------------------------------
+  REENTRANT: 'The contract rejected a nested call for safety. Nothing moved.',
+  Reentrant: 'The contract rejected a nested call for safety. Nothing moved.',
+  ReentrantCall: 'The contract rejected a nested call for safety. Nothing moved.',
+  NOT_OWNER: 'Your wallet is not the owner of this contract.',
+  NotOwner: 'Your wallet is not the owner of this contract.',
+  Unauthorized: 'Your wallet is not authorised to make this call.',
+  ZERO_ADDRESS: 'A required address was zero.',
+  ZeroAddress: 'A required address was zero.',
+  REFUND_FAILED: 'The excess amount could not be refunded, so the whole transaction failed.',
+  RefundFailed: 'The excess amount could not be refunded, so the whole transaction failed.',
+  ALLOWANCE: 'The approval on the quote asset does not cover this amount.',
+  BALANCE: 'Your balance of the quote asset is lower than the amount this call needs.',
+};
+
+export interface DecodedLaunchRevert {
+  /** The contract's own error identifier (e.g. `POOL_PRICE_MISMATCH`), or null when unrecognised. */
+  readonly raw: string | null;
+  /** A sentence, always present. */
+  readonly message: string;
+}
+
+const ERROR_STRING_SELECTOR = '0x08c379a0';
+const PANIC_SELECTOR = '0x4e487b71';
+
+/**
+ * Every error in a `cause` chain, top first. DUCK-TYPED, not `instanceof BaseError`: a consumer
+ * with its own copy of viem (a monorepo app, a bundler that did not dedupe) throws errors from a
+ * different class object, and an `instanceof` check would silently decode nothing.
+ */
+function causeChain(error: unknown): readonly Record<string, unknown>[] {
+  const out: Record<string, unknown>[] = [];
+  let current: unknown = error;
+  for (let depth = 0; depth < 16 && current && typeof current === 'object'; depth += 1) {
+    out.push(current as Record<string, unknown>);
+    current = (current as { cause?: unknown }).cause;
+  }
+  return out;
+}
+
+const isHexData = (value: unknown): value is Hex => typeof value === 'string' && isHex(value) && value.length >= 10;
+
+/** The revert data hex carried anywhere in a viem error chain, or null. */
+export function revertDataOf(error: unknown): Hex | null {
+  for (const e of causeChain(error)) {
+    if (isHexData(e['raw'])) return e['raw'];
+    if (isHexData(e['data'])) return e['data'];
+  }
+  return null;
+}
+
+/** The identifier revert data names: an `Error(string)` reason or a custom error's name. */
+export function revertIdentifier(data: Hex): string | null {
+  const selector = data.slice(0, 10).toLowerCase();
+  try {
+    if (selector === ERROR_STRING_SELECTOR) {
+      const decoded = decodeErrorResult({ abi: [{ type: 'error', name: 'Error', inputs: [{ type: 'string' }] }], data });
+      const reason = String(decoded.args?.[0] ?? '').trim();
+      return reason.length > 0 ? reason : null;
+    }
+    if (selector === PANIC_SELECTOR) return 'Panic';
+    const decoded = decodeErrorResult({ abi: launchErrorsAbi, data });
+    return decoded.errorName;
+  } catch {
+    return null;
+  }
+}
+
+/** The mapped sentence for a contract identifier, or null when unrecognised. */
+export function explainLaunchRevert(identifier: string | null): string | null {
+  if (!identifier) return null;
+  return LAUNCH_REVERT_REASONS[identifier] ?? null;
+}
+
+/**
+ * Decode an RPC/contract failure into `{ raw, message }`. Accepts a viem error
+ * (from `simulateContract`, `call` or `sendTransaction`), any error whose cause
+ * chain carries revert data, or raw revert data.
+ */
+export function decodeLaunchRevert(error: unknown): DecodedLaunchRevert {
+  const data = isHexData(error) ? error : revertDataOf(error);
+  // A viem `ContractFunctionRevertedError` already carries the reason / errorName; take it from
+  // wherever in the chain it sits. An `Error(string)` reason is the identifier itself.
+  let identifier: string | null = null;
+  for (const e of causeChain(error)) {
+    const reason = e['reason'];
+    if (typeof reason === 'string' && reason.trim()) {
+      identifier = reason.trim();
+      break;
+    }
+    const nested = e['data'];
+    const errorName = nested && typeof nested === 'object' ? (nested as { errorName?: unknown }).errorName : undefined;
+    if (typeof errorName === 'string' && errorName !== 'Error') {
+      identifier = errorName;
+      break;
+    }
+  }
+  if (identifier === null && data) identifier = revertIdentifier(data);
+
+  const mapped = explainLaunchRevert(identifier);
+  if (mapped) return { raw: identifier, message: mapped };
+  if (identifier) return { raw: identifier, message: 'The contract rejected these settings.' };
+  const top = causeChain(error)[0];
+  const short = top && typeof top['shortMessage'] === 'string' ? (top['shortMessage'] as string) : null;
+  if (short) return { raw: null, message: short };
+  return { raw: null, message: error instanceof Error ? error.message : 'The transaction could not be simulated.' };
+}
+
+/** A mined-but-reverted receipt carries no reason — the node discarded it. */
+export const REVERTED_ON_CHAIN =
+  'The transaction was mined and the contract rejected it. Gas was spent; nothing else moved. Open it on the explorer for the failing call.';

package/src/launch/salt.ts

@@ -0,0 +1,216 @@
+import { concat, encodeAbiParameters, getAddress, keccak256 } from 'viem';
+
+/**
+ * Salt handling for the two CREATE2 launch paths — a pure port of the web app's
+ * `features/launch/salt.ts`, held identical by test.
+ *
+ * ─── EVERY PEDDLES ADDRESS ENDS IN `1978` ────────────────────────────────────
+ * The platform contracts do, and launched tokens do too, with no option to choose
+ * otherwise. So there is no vanity field: a launch MINES a salt whose address
+ * carries the suffix, and the creator sees the address they will get.
+ *
+ * A salt does two jobs, and only one of them is the suffix:
+ *
+ *   1. It picks the address. Both contracts mix the variant AND `msg.sender`
+ *      into it (`keccak256(abi.encode(variant, sender, salt))`), so a salt only
+ *      ever addresses the caller's OWN CREATE2 space.
+ *   2. It defeats front-running. The token address is an input to the pool key,
+ *      so anyone who can predict it can open that pool first at a price of their
+ *      choosing — the launch then reverts `POOL_PRICE_MISMATCH`. Mining starts
+ *      from a CSPRNG value, so the mined salt is as unguessable as a random one.
+ *
+ * ─── LOCAL DERIVATION, CONTRACT CONFIRMATION ─────────────────────────────────
+ * Mining computes the address locally (65,536 expected attempts is not an RPC
+ * job), and the plan builders then CONFIRM the candidate with the contract's own
+ * `getPeddlesAddress` / `predictCoin` before it is shown or submitted.
+ */
+
+/** The required address suffix, lowercase hex, no `0x`. */
+export const ADDRESS_SUFFIX = '1978';
+
+/**
+ * `keccak256(abi.encode(uint8 variant, address sender, bytes32 salt))` — the
+ * salt binding both `PeddlesStockLaunchpad._boundSalt` and
+ * `PeddlesFactoryV20._boundSalt` apply.
+ */
+export function boundSalt(variant: number, sender: `0x${string}`, salt: `0x${string}`): `0x${string}` {
+  return keccak256(
+    encodeAbiParameters(
+      [{ type: 'uint8' }, { type: 'address' }, { type: 'bytes32' }],
+      [variant, sender, salt],
+    ),
+  );
+}
+
+/** Standard CREATE2: `keccak256(0xff ‖ deployer ‖ salt ‖ initCodeHash)[12:]`. */
+export function create2Address(
+  deployer: `0x${string}`,
+  salt: `0x${string}`,
+  initCodeHash: `0x${string}`,
+): `0x${string}` {
+  const digest = keccak256(concat(['0xff', deployer, salt, initCodeHash]));
+  return getAddress(`0x${digest.slice(26)}`);
+}
+
+export function hasSuffix(address: string, suffix: string = ADDRESS_SUFFIX): boolean {
+  return address.toLowerCase().endsWith(suffix.toLowerCase());
+}
+
+/**
+ * A fresh unguessable salt from the platform CSPRNG (`crypto.getRandomValues`,
+ * never `Math.random`): this value is the only thing standing between a launch
+ * and a mempool watcher who opens the pool first.
+ */
+export function randomSalt(): `0x${string}` {
+  const bytes = new Uint8Array(32);
+  // Typed structurally: this package ships no DOM or Node lib, and both runtimes expose the same API.
+  const cryptoApi = (globalThis as unknown as { crypto?: { getRandomValues(array: Uint8Array): Uint8Array } }).crypto;
+  if (!cryptoApi) throw new Error('No CSPRNG (globalThis.crypto) is available; refusing to mine a guessable salt.');
+  cryptoApi.getRandomValues(bytes);
+  return `0x${Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('')}`;
+}
+
+/** `0x00…00` — the salt a caller means by "none", still bound to the sender. */
+export const ZERO_SALT: `0x${string}` = `0x${'0'.repeat(64)}`;
+
+export interface MineParams {
+  /** The contract that runs CREATE2 — the launchpad or the factory. */
+  readonly deployer: `0x${string}`;
+  /** The variant byte the contract mixes into the salt. */
+  readonly variant: number;
+  /** The `msg.sender` the contract binds the salt to — the creator, or the orchestrator. */
+  readonly sender: `0x${string}`;
+  readonly initCodeHash: `0x${string}`;
+  readonly suffix?: string;
+  /** Anything with an `aborted` flag — an `AbortSignal`, or a plain object a caller flips. */
+  readonly signal?: { readonly aborted: boolean };
+  /** Called every chunk with the attempt count so far. */
+  readonly onProgress?: (attempts: number) => void;
+  /**
+   * Hard ceiling on attempts. A 4-hex suffix is 1 in 65,536; the default is ~60×
+   * that, so hitting it means something is wrong with the inputs, not bad luck,
+   * and the caller fails closed rather than looping forever.
+   */
+  readonly maxAttempts?: number;
+}
+
+export interface MinedSalt {
+  readonly salt: `0x${string}`;
+  /** The locally derived address. Confirm it with the contract before use. */
+  readonly address: `0x${string}`;
+  readonly attempts: number;
+}
+
+export class MiningAbortedError extends Error {
+  constructor() {
+    super('Address mining was cancelled.');
+    this.name = 'MiningAbortedError';
+  }
+}
+
+export class MiningExhaustedError extends Error {
+  readonly attempts: number;
+  constructor(suffix: string, attempts: number) {
+    super(`No address ending in ${suffix} was found after ${attempts.toLocaleString()} attempts.`);
+    this.name = 'MiningExhaustedError';
+    this.attempts = attempts;
+  }
+}
+
+const CHUNK = 4096;
+
+function hexToBytes(hex: string): Uint8Array {
+  const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+  const out = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < out.length; i += 1) out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+
+function bytesToHex(bytes: Uint8Array): `0x${string}` {
+  let s = '0x';
+  for (const b of bytes) s += b.toString(16).padStart(2, '0');
+  return s as `0x${string}`;
+}
+
+/**
+ * Find a salt whose bound CREATE2 address ends in `suffix`.
+ *
+ * The hot loop works on bytes: two keccaks per attempt, preimages preallocated
+ * once, the suffix compared on the raw hash bytes. The winner is re-derived
+ * through `boundSalt` + `create2Address` before it is returned, so the fast path
+ * can never quietly disagree with the readable one. Runs in chunks and yields
+ * between them, so a caller can cancel through `signal` and a main thread keeps
+ * painting.
+ */
+export async function mineSalt(params: MineParams): Promise<MinedSalt> {
+  const {
+    deployer,
+    variant,
+    sender,
+    initCodeHash,
+    suffix = ADDRESS_SUFFIX,
+    signal,
+    onProgress,
+    maxAttempts = 4_000_000,
+  } = params;
+
+  if (!/^[0-9a-fA-F]+$/.test(suffix) || suffix.length % 2 !== 0) {
+    throw new Error(`The address suffix must be whole hex bytes; got "${suffix}".`);
+  }
+  const want = hexToBytes(suffix);
+
+  // abi.encode(uint8 variant, address sender, bytes32 salt): three 32-byte words.
+  const bound = new Uint8Array(96);
+  bound[31] = variant & 0xff;
+  bound.set(hexToBytes(sender), 32 + 12);
+  const saltView = bound.subarray(64, 96);
+  saltView.set(hexToBytes(randomSalt()));
+
+  // 0xff ‖ deployer ‖ boundSalt ‖ initCodeHash.
+  const create2 = new Uint8Array(85);
+  create2[0] = 0xff;
+  create2.set(hexToBytes(deployer), 1);
+  create2.set(hexToBytes(initCodeHash), 53);
+
+  const bump = () => {
+    for (let i = 31; i >= 0; i -= 1) {
+      saltView[i] = (saltView[i]! + 1) & 0xff;
+      if (saltView[i] !== 0) break;
+    }
+  };
+
+  let attempts = 0;
+
+  while (attempts < maxAttempts) {
+    if (signal?.aborted) throw new MiningAbortedError();
+
+    for (let i = 0; i < CHUNK && attempts < maxAttempts; i += 1) {
+      create2.set(keccak256(bound, 'bytes'), 21);
+      const digest = keccak256(create2, 'bytes');
+      attempts += 1;
+
+      let hit = true;
+      for (let j = 0; j < want.length; j += 1) {
+        if (digest[32 - want.length + j] !== want[j]) {
+          hit = false;
+          break;
+        }
+      }
+      if (hit) {
+        const salt = bytesToHex(saltView);
+        const address = create2Address(deployer, boundSalt(variant, sender, salt), initCodeHash);
+        if (!hasSuffix(address, suffix)) {
+          throw new Error('The address miner disagreed with itself; nothing was reserved.');
+        }
+        return { salt, address, attempts };
+      }
+      bump();
+    }
+
+    onProgress?.(attempts);
+    // A macrotask yield (`setTimeout(0)`), so a main-thread caller gets to paint between chunks.
+    await new Promise<void>((resolve) => (globalThis as unknown as { setTimeout(fn: () => void, ms: number): unknown }).setTimeout(resolve, 0));
+  }
+
+  throw new MiningExhaustedError(suffix, attempts);
+}