@peddles/sdk 0.2.0

package/src/abis.ts

@@ -0,0 +1,35 @@
+/**
+ * The ABI fragments the SDK's public surface needs — and nothing else.
+ *
+ * DELIBERATELY PARTIAL. These are narrowed to the functions this package
+ * exposes, not dumps of the full artifacts. A published ABI is API: every
+ * fragment shipped here is one this package promises to keep working, so the
+ * ones an integrator has no business calling (owner setters, one-shot bootstrap
+ * calls, indexer hooks) are absent rather than available-but-undocumented.
+ *
+ * NARROWED, NOT HAND-TYPED. Which names ship is decided in
+ * `script/generate-abis.mjs`; every fragment's shape is copied from the
+ * compiler's own output (`contracts/out`) into `abis.generated.ts`.
+ *
+ * `PeddlesCreatorFeeHook` is intentionally absent: it is not part of the
+ * fixed-terms fee model. Every launch pool's terms are read from
+ * `PeddlesFeeHook` (`feeHookAbi`).
+ */
+export {
+  factoryAbi,
+  clogVaultAbi,
+  clogVaultFactoryAbi,
+  erc20Abi,
+  tokenV20Abi,
+  feeHookAbi,
+  stockLaunchpadAbi,
+  holderRewardsAbi,
+  nftFactoryAbi,
+  nftCollectionAbi,
+  nftFeeDistributorFactoryAbi,
+  nftFeeDistributorAbi,
+  nftBondingGraduationOrchestratorAbi,
+  nftStockGraduationOrchestratorAbi,
+  liquidityExecutorAbi,
+  routeSwapRouterAbi,
+} from './abis.generated.js';

package/src/artDex.ts

@@ -0,0 +1,254 @@
+import type { ReadClient } from './client.js';
+import type { Address, Hex } from 'viem';
+import { encodeAbiParameters, keccak256 } from 'viem';
+import {
+  nftBondingGraduationOrchestratorAbi,
+  nftCollectionAbi,
+  nftFactoryAbi,
+  nftFeeDistributorAbi,
+  nftFeeDistributorFactoryAbi,
+  nftStockGraduationOrchestratorAbi,
+} from './abis.js';
+
+/**
+ * Art->DEX: a Peddles NFT collection launches ONE coin, paired to WETH or a tokenised stock, and may
+ * commit — permanently — a share of the creator's fee streams to its NFT holders.
+ *
+ * The commitment is the collection's write-once `holderRewards` binding to its canonical
+ * `PeddlesNftFeeDistributor` (made by `PeddlesNftFeeDistributorFactory`), plus the `holderShareBps`
+ * the creator passes at launch (0..10000). Nobody can change either afterwards.
+ *
+ * Addresses are parameters here rather than looked up from `DEPLOYMENTS`: the distributor factory ships
+ * with the Art->DEX deployment, and an address book that predates it has no entry to look up.
+ */
+
+const ZERO = /^0x0{40}$/i;
+const BPS = 10_000;
+
+/** Bps bound shared by every holder-share argument. Throws rather than letting the chain revert. */
+function assertBps(name: string, v: number): void {
+  if (!Number.isInteger(v) || v < 0 || v > BPS) throw new RangeError(`${name} must be an integer 0..10000, got ${v}`);
+}
+
+/* ------------------------------ relayed stock launch consent ------------------------------ */
+
+export interface RelayParams {
+  readonly chainId: number;
+  /** The PeddlesNftStockGraduationOrchestrator the consent is for. */
+  readonly orchestrator: Address;
+  readonly collection: Address;
+  readonly name: string;
+  readonly symbol: string;
+  readonly quote: Address;
+  readonly holderShareBps: number;
+}
+
+/**
+ * `relayParamsHash` computed off chain — `keccak256(abi.encode(chainid, orchestrator, collection, name,
+ * symbol, quote, holderShareBps))`, exactly as the orchestrator hashes it. The collection owner signs
+ * `setStockGraduationOptIn(collection, hash)`; a relay whose parameters hash to anything else reverts.
+ * Chain id and orchestrator are part of it, so consent never carries across chains or deployments.
+ */
+export function relayParamsHash(p: RelayParams): Hex {
+  assertBps('holderShareBps', p.holderShareBps);
+  return keccak256(
+    encodeAbiParameters(
+      [{ type: 'uint256' }, { type: 'address' }, { type: 'address' }, { type: 'string' }, { type: 'string' }, { type: 'address' }, { type: 'uint16' }],
+      [BigInt(p.chainId), p.orchestrator, p.collection, p.name, p.symbol, p.quote, p.holderShareBps],
+    ),
+  );
+}
+
+/** Request for `setStockGraduationOptIn(collection, relayParamsHash(p))` (collection owner only). Zero revokes. */
+export function stockGraduationOptInRequest(p: RelayParams) {
+  return {
+    address: p.orchestrator,
+    abi: nftStockGraduationOrchestratorAbi,
+    functionName: 'setStockGraduationOptIn',
+    args: [p.collection, relayParamsHash(p)],
+  } as const;
+}
+
+/* ------------------------------ launch requests ------------------------------ */
+
+export interface StockTermsLaunch {
+  readonly orchestrator: Address;
+  readonly collection: Address;
+  readonly name: string;
+  readonly symbol: string;
+  readonly quote: Address;
+  /** All-in pool tax, bps (100..1000). Permanent. */
+  readonly creatorTaxBps: number;
+  /** Creator's share of the tax above 1.00%, bps. Permanent. */
+  readonly excessToCreatorBps: number;
+  /** Share of the creator streams paid to NFT holders, bps. 0 unless the collection is committed. Permanent. */
+  readonly holderShareBps: number;
+  /** Quote base units for the in-launch dev buy (0 = none); pulled from the caller, so approve first. */
+  readonly devBuyQuoteIn: bigint;
+  readonly minTokensOut: bigint;
+  /** The launchpad's native launch fee, forwarded as msg.value. */
+  readonly launchFee: bigint;
+}
+
+/** Request for `graduateToStockWithTerms` (collection owner only). */
+export function graduateToStockWithTermsRequest(l: StockTermsLaunch) {
+  assertBps('holderShareBps', l.holderShareBps);
+  assertBps('excessToCreatorBps', l.excessToCreatorBps);
+  return {
+    address: l.orchestrator,
+    abi: nftStockGraduationOrchestratorAbi,
+    functionName: 'graduateToStockWithTerms',
+    args: [
+      {
+        collection: l.collection,
+        name: l.name,
+        symbol: l.symbol,
+        quote: l.quote,
+        creatorTaxBps: l.creatorTaxBps,
+        excessToCreatorBps: l.excessToCreatorBps,
+        holderShareBps: l.holderShareBps,
+        devBuyQuoteIn: l.devBuyQuoteIn,
+        minTokensOut: l.minTokensOut,
+      },
+    ],
+    value: l.launchFee,
+  } as const;
+}
+
+/**
+ * Request for `graduateAndBuy(input, holderShareBps, devBuyValue, minTokensOut)` — the ONLY WETH-path
+ * entry since 94d6564 (`graduate` was removed). A plain launch is `holderShareBps = 0, devBuyValue = 0,
+ * minTokensOut = 0`. `value` must cover the orchestrator's `launchFee()` (read it live —
+ * `readOrchestratorLaunchFee` in `@peddles/sdk/launch`) `+ input.factoryValue + devBuyValue`; a relay of
+ * a committed graduation carries exactly `launchFee()` (`RELAY_FEE_ONLY`).
+ *
+ * `input` is the orchestrator's `GraduateInput` tuple, built by the launch kit exactly as for any V20
+ * launch; this helper only positions the Art->DEX arguments around it.
+ */
+export function graduateAndBuyRequest(p: {
+  readonly orchestrator: Address;
+  readonly input: unknown;
+  readonly holderShareBps: number;
+  readonly devBuyValue: bigint;
+  readonly minTokensOut: bigint;
+  readonly value: bigint;
+}) {
+  assertBps('holderShareBps', p.holderShareBps);
+  if (p.devBuyValue > p.value) throw new RangeError('devBuyValue exceeds value');
+  return {
+    address: p.orchestrator,
+    abi: nftBondingGraduationOrchestratorAbi,
+    functionName: 'graduateAndBuy',
+    args: [p.input, p.holderShareBps, p.devBuyValue, p.minTokensOut],
+    value: p.value,
+  } as const;
+}
+
+/* ------------------------------ reads ------------------------------ */
+
+/** The canonical distributor address for `collection` (CREATE2; exists or not). */
+export async function predictDistributor(client: ReadClient, distributorFactory: Address, collection: Address): Promise<Address> {
+  return (await client.readContract({ address: distributorFactory, abi: nftFeeDistributorFactoryAbi, functionName: 'predict', args: [collection] })) as Address;
+}
+
+export interface HolderCommitment {
+  /** True when the collection is bound to its canonical Peddles distributor. */
+  readonly committed: boolean;
+  /** The bound `holderRewards` (zero = none). */
+  readonly holderRewards: Address;
+  /** True when the Peddles NFT factory made this collection. */
+  readonly peddlesCollection: boolean;
+}
+
+/**
+ * Whether a collection's creator streams are committed to its holders — the same three reads the
+ * orchestrators make: `holderRewards()`, `factory.isDistributor(d)`, `d.collection() == collection`.
+ * Also reports factory provenance, which the orchestrators do NOT check.
+ */
+export async function getHolderCommitment(
+  client: ReadClient,
+  a: { nftFactory: Address; distributorFactory: Address; collection: Address },
+): Promise<HolderCommitment> {
+  const [holderRewards, peddlesCollection] = await Promise.all([
+    client.readContract({ address: a.collection, abi: nftCollectionAbi, functionName: 'holderRewards' }) as Promise<Address>,
+    client.readContract({ address: a.nftFactory, abi: nftFactoryAbi, functionName: 'isPeddlesCollection', args: [a.collection] }) as Promise<boolean>,
+  ]);
+  if (ZERO.test(holderRewards)) return { committed: false, holderRewards, peddlesCollection };
+  const isDistributor = (await client.readContract({
+    address: a.distributorFactory,
+    abi: nftFeeDistributorFactoryAbi,
+    functionName: 'isDistributor',
+    args: [holderRewards],
+  })) as boolean;
+  if (!isDistributor) return { committed: false, holderRewards, peddlesCollection };
+  const bound = (await client.readContract({ address: holderRewards, abi: nftFeeDistributorAbi, functionName: 'collection' })) as Address;
+  return { committed: bound.toLowerCase() === a.collection.toLowerCase(), holderRewards, peddlesCollection };
+}
+
+export interface DistributorState {
+  readonly distributor: Address;
+  readonly collection: Address;
+  /** Zero until launch. */
+  readonly quote: Address;
+  readonly token: Address;
+  readonly holderShareBps: number;
+  readonly assetsInitialized: boolean;
+  readonly creatorShareOwed: { readonly quote: bigint; readonly token: bigint };
+  readonly owedToHolders: { readonly quote: bigint; readonly token: bigint };
+  /** False while minted pieces are unmirrored — holder distribution waits until they are synced. */
+  readonly mirrorComplete: boolean;
+}
+
+export async function getDistributorState(client: ReadClient, distributor: Address): Promise<DistributorState> {
+  const base = { address: distributor, abi: nftFeeDistributorAbi } as const;
+  const [collection, quote, token, holderShareBps, assetsInitialized, creatorShareOwed, owedToHolders, mirrorComplete] = await client.multicall({
+    allowFailure: false,
+    contracts: [
+      { ...base, functionName: 'collection' },
+      { ...base, functionName: 'quote' },
+      { ...base, functionName: 'token' },
+      { ...base, functionName: 'holderShareBps' },
+      { ...base, functionName: 'assetsInitialized' },
+      { ...base, functionName: 'creatorShareOwed' },
+      { ...base, functionName: 'owedToHolders' },
+      { ...base, functionName: 'mirrorComplete' },
+    ],
+  });
+  const [cq, ct] = creatorShareOwed as readonly [bigint, bigint];
+  const [hq, ht] = owedToHolders as readonly [bigint, bigint];
+  return {
+    distributor,
+    collection: collection as Address,
+    quote: quote as Address,
+    token: token as Address,
+    holderShareBps: Number(holderShareBps),
+    assetsInitialized: assetsInitialized as boolean,
+    creatorShareOwed: { quote: cq, token: ct },
+    owedToHolders: { quote: hq, token: ht },
+    mirrorComplete: mirrorComplete as boolean,
+  };
+}
+
+export interface HolderClaimable {
+  readonly quote: bigint;
+  readonly token: bigint;
+  /** Shares the distributor has mirrored for the holder. */
+  readonly shares: bigint;
+  /** Pieces the holder holds on the collection. */
+  readonly pieces: bigint;
+  /** `shares != pieces`: claims under-accrue until `syncAccount(holder)` runs. */
+  readonly needsSync: boolean;
+}
+
+export async function holderClaimable(client: ReadClient, distributor: Address, collection: Address, holder: Address): Promise<HolderClaimable> {
+  const [pending, shares, pieces] = await client.multicall({
+    allowFailure: false,
+    contracts: [
+      { address: distributor, abi: nftFeeDistributorAbi, functionName: 'pending', args: [holder] },
+      { address: distributor, abi: nftFeeDistributorAbi, functionName: 'sharesOf', args: [holder] },
+      { address: collection, abi: nftCollectionAbi, functionName: 'balanceOf', args: [holder] },
+    ],
+  });
+  const [quote, token] = pending as readonly [bigint, bigint];
+  return { quote, token, shares: shares as bigint, pieces: pieces as bigint, needsSync: (shares as bigint) !== (pieces as bigint) };
+}

package/src/client.ts

@@ -0,0 +1,10 @@
+import type { PublicClient } from 'viem';
+
+/**
+ * The client every SDK read takes: any viem client that can `readContract`, `multicall` and
+ * `getBalance`. Narrower than `PublicClient` on purpose — a `PublicClient` built for a chain with its
+ * own formatters (Base and every OP-stack chain add `deposit` transactions) is NOT assignable to the
+ * generic `PublicClient`, so typing parameters that way made `createPublicClient({ chain: base })`
+ * a compile error for every Base integrator. Only the three methods the SDK calls are required.
+ */
+export type ReadClient = Pick<PublicClient, 'readContract' | 'multicall' | 'getBalance'>;

package/src/clog.ts

@@ -0,0 +1,171 @@
+import type { ReadClient } from './client.js';
+import type { Address } from 'viem';
+import { clogVaultAbi, clogVaultFactoryAbi, erc20Abi, factoryAbi } from './abis.js';
+import { addressOf } from './deployments.js';
+
+/**
+ * The Clog launch type, read from the chain.
+ *
+ * A clog withholds a share of a launch's supply in a `PeddlesClogVault` and
+ * sells it into that launch's own pool a capped slice at a time. The proceeds
+ * (native) STAY IN THE VAULT until the creator calls `withdrawProceeds`, and a
+ * creator-set release floor bounds the price a release may sell at. It funds marketing without the creator putting up
+ * capital — and it only ever extracts from volume that actually arrived, since
+ * a sale into an empty book returns nothing and reverts.
+ */
+
+/** A launch type's declared economics. Write-once at variant registration. */
+export interface VariantAllocation {
+  readonly liquidityBps: number;
+  readonly airdropBps: number;
+  readonly vestingBps: number;
+  readonly burnBps: number;
+  readonly clogBps: number;
+  /** Per-release cap, in bps OF TOTAL SUPPLY — not of the allocation. */
+  readonly clogSliceBps: number;
+  readonly clogMinIntervalSeconds: bigint;
+}
+
+/** One clog vault's live state. */
+export interface ClogState {
+  readonly vault: Address;
+  readonly token: Address;
+  readonly creator: Address;
+  readonly router: Address;
+  /** Raw units still held, i.e. not yet sold. */
+  readonly held: bigint;
+  /** Raw units sold to date, across every release. */
+  readonly totalSold: bigint;
+  /** Max raw units one release may sell. */
+  readonly sliceCap: bigint;
+  readonly minIntervalSeconds: bigint;
+  /** What `release` would sell right now. */
+  readonly nextSlice: bigint;
+  /** Unix seconds at which `release` stops reverting `TooSoon`. */
+  readonly readyAt: bigint;
+  /** Native proceeds held by the vault, owed to the creator (`withdrawProceeds`). */
+  readonly proceedsOwed: bigint;
+  /** The creator's minimum release price, 1e18-scaled quote per token; 0 = none. */
+  readonly releaseFloorX18: bigint;
+}
+
+/**
+ * Read a launch type's allocation.
+ *
+ * `registerVariant` is write-once, so this is the deal a creator and every
+ * buyer of their token accepted — it cannot be changed under them afterwards.
+ * Read it rather than assuming: the shares differ per launch type, and a clog
+ * type is not 100% liquidity.
+ */
+export async function getVariantAllocation(
+  client: ReadClient,
+  chainId: number,
+  variant: number,
+): Promise<VariantAllocation> {
+  const a = (await client.readContract({
+    address: addressOf(chainId, 'PeddlesFactoryV20'),
+    abi: factoryAbi,
+    functionName: 'variantAllocation',
+    args: [variant],
+  })) as {
+    liquidityBps: number;
+    airdropBps: number;
+    vestingBps: number;
+    burnBps: number;
+    clogBps: number;
+    clogSliceBps: number;
+    clogMinInterval: bigint;
+  };
+
+  return {
+    liquidityBps: a.liquidityBps,
+    airdropBps: a.airdropBps,
+    vestingBps: a.vestingBps,
+    burnBps: a.burnBps,
+    clogBps: a.clogBps,
+    clogSliceBps: a.clogSliceBps,
+    clogMinIntervalSeconds: a.clogMinInterval,
+  };
+}
+
+/** The clog vault a launch's orchestrator created for `token`, or null. */
+export async function getClogVault(
+  client: ReadClient,
+  chainId: number,
+  token: Address,
+): Promise<Address | null> {
+  const vault = (await client.readContract({
+    address: addressOf(chainId, 'PeddlesClogVaultFactory'),
+    abi: clogVaultFactoryAbi,
+    functionName: 'vaultOf',
+    args: [addressOf(chainId, 'PeddlesLaunchOrchestratorV20'), token],
+  })) as Address;
+  return /^0x0{40}$/i.test(vault) ? null : vault;
+}
+
+/** Everything about one clog vault, in a single multicall. */
+export async function getClogState(client: ReadClient, vault: Address): Promise<ClogState> {
+  const base = { address: vault, abi: clogVaultAbi } as const;
+  const [token, creator, router, sliceCap, minInterval, totalSold, preview, releaseFloorX18] = await client.multicall({
+    allowFailure: false,
+    contracts: [
+      { ...base, functionName: 'token' },
+      { ...base, functionName: 'creator' },
+      { ...base, functionName: 'router' },
+      { ...base, functionName: 'sliceCap' },
+      { ...base, functionName: 'minInterval' },
+      { ...base, functionName: 'totalSold' },
+      { ...base, functionName: 'previewRelease' },
+      { ...base, functionName: 'releaseFloorX18' },
+    ],
+  });
+
+  const [held, proceedsOwed] = await Promise.all([
+    client.readContract({ address: token as Address, abi: erc20Abi, functionName: 'balanceOf', args: [vault] }) as Promise<bigint>,
+    client.getBalance({ address: vault }),
+  ]);
+
+  const [nextSlice, readyAt] = preview as readonly [bigint, bigint];
+
+  return {
+    vault,
+    token: token as Address,
+    creator: creator as Address,
+    router: router as Address,
+    held,
+    totalSold: totalSold as bigint,
+    sliceCap: sliceCap as bigint,
+    minIntervalSeconds: minInterval as bigint,
+    nextSlice,
+    readyAt,
+    proceedsOwed,
+    releaseFloorX18: releaseFloorX18 as bigint,
+  };
+}
+
+/**
+ * What share of INFLOWS a clog routes to the creator, given its share of supply.
+ *
+ * THESE ARE NOT THE SAME NUMBER, and the second is the one that matters to a
+ * buyer. The allocation is a share of supply, but it is sold into the pool the
+ * buyer is buying from, so it captures a much larger share of the money coming
+ * in. Surface it wherever the allocation is shown: a launch page that says "5%"
+ * and stops has told the buyer the smaller of two true numbers.
+ *
+ * The model (exact, bigint, documented in `clogInflow.ts`) lives in its own
+ * import-free module and is re-exported here.
+ */
+export {
+  CLOG_MODEL_FLOW_MULTIPLE,
+  CLOG_TABLE_SLICE_BPS,
+  clogShareOfInflows,
+  clogShareOfInflowsFromBps,
+  clogInflowShareBps,
+  inflowShareBps,
+} from './clogInflow.js';
+export type { ShareOfInflows, ClogModelInput } from './clogInflow.js';
+
+/** True when `release` would not revert `TooSoon`. */
+export function isReleaseReady(state: ClogState, nowSeconds: bigint): boolean {
+  return nowSeconds >= state.readyAt;
+}

package/src/clogInflow.ts

@@ -0,0 +1,217 @@
+/**
+ * What share of the money buyers put in a clog routes to the creator.
+ *
+ * A clog allocation is a share of SUPPLY, but it is sold into the pool buyers are
+ * buying from, so it captures a far larger share of the money coming in. That
+ * second number is the one a buyer is accepting, and it must be stated wherever
+ * the allocation is. This module derives it; nothing here is a lookup table.
+ *
+ * Pure: no imports, bigint only, no floating point at any step. Every step is
+ * exact rational arithmetic, so the result is a fraction `num / den`; the only
+ * rounding is in `clogInflowShareBps`, once, at the end.
+ *
+ * SINGLE SOURCE OF TRUTH. `apps/web/src/features/launch/clogInflow.ts` carries a
+ * copy (the web app does not depend on this package). `__tests__/clogInflow.test.ts`
+ * imports that copy and holds the two to identical fractions over a grid, so a
+ * change to one without the other fails the SDK's tests.
+ *
+ * ── THE MODEL ───────────────────────────────────────────────────────────────
+ * Pure buy flow — nobody but the clog ever sells. That is the most favourable
+ * case for the design: any real selling makes the clog sell into a weaker pool.
+ *
+ *   The pool. A Peddles launch opens a single-sided position from the launch
+ *   price upward holding the liquidity share `x0 = supply - clog`. For such a
+ *   position, token reserve `x` and quote `y` satisfy
+ *
+ *       x · (y + x0·p0) = x0² · p0          (a constant product, k)
+ *
+ *   i.e. constant product against a virtual quote reserve `x0·p0`. Write
+ *   `q = y + x0·p0`, so `q0 = x0·p0` and `k = x0·q0`.
+ *
+ *   One round. Buyers spend `B` (a buy never changes k):   q  ←  q + B
+ *   then the clog sells `s = min(slice, remaining)` tokens:
+ *
+ *       q  ←  k · q / (k + s · q)           (x ← x + s,  q = k / x)
+ *
+ *   Rounds repeat until the clog is empty. After `n` rounds buyers have put in
+ *   `n·B`, and the pool holds `q_n − q0` of it; everything else was paid out to
+ *   the creator. So, exactly:
+ *
+ *       share of inflows  =  1 − (q_n − q0) / (n · B)
+ *
+ *   Buy flow per round — THE ONE ASSUMPTION. `B = flowMultiple × slice × p0`:
+ *   buyers spend between releases `flowMultiple` times what a slice was worth at
+ *   the launch price. Default `CLOG_MODEL_FLOW_MULTIPLE` (100).
+ *
+ *   p0 cancels. Measuring quote in units of `p0` makes every term an integer
+ *   count of tokens (`q0 = x0`, `k = x0²`, `B = flowMultiple × slice`), so the
+ *   result depends only on (supply, clog, slice) and the flow multiple — never
+ *   on the launch price, which is why it can be stated before the pool exists.
+ *
+ *   The floor. A single-sided position holds no quote below its launch price, so
+ *   a release can never take the price under `p0`. If a round's sale would, the
+ *   model does not apply and the functions return null rather than a number from
+ *   a pool that cannot exist. At flowMultiple = 100 this cannot happen anywhere
+ *   in the range the factory accepts (clog ≤ `PeddlesFactoryV20.CLOG_BPS_MAX`,
+ *   25%): a round starts at `q ≥ q0`, its buys take at least `x0·B / (x0 + B)`
+ *   tokens out of the pool, and a sale `s ≤ clog` fits back under the floor
+ *   whenever `99·x0 ≥ 100·s` — true for every `x0 ≥ 75%` and `s ≤ 25%`.
+ *
+ * ── REFERENCE ───────────────────────────────────────────────────────────────
+ * With slices of 1% of supply (`CLOG_TABLE_SLICE_BPS`) and flowMultiple = 100
+ * this reproduces the policy table in CLAUDE.md at its 0.1% resolution
+ * (5% → 16.5%, 10% → 37.1%, 15% → 54.6%, 25% → 75.0%). A launch type's real
+ * slice is smaller — the live Sepolia Clog type sells 5% in 0.25% slices, which
+ * is ≈14.2% — so pass the slice the chain reports, never the table's.
+ */
+
+/**
+ * Buyer spend between two clog releases, as a multiple of what one slice was
+ * worth at the launch price. The one assumption in the model; see the header.
+ */
+export const CLOG_MODEL_FLOW_MULTIPLE = 100n;
+
+/** The slice (1% of supply) at which the model reproduces the CLAUDE.md policy table. */
+export const CLOG_TABLE_SLICE_BPS = 100n;
+
+/** More rounds than any registrable launch type can need (25% in 1-unit slices of 10,000). */
+const MAX_ROUNDS = 100_000n;
+
+const BPS = 10_000n;
+
+export interface ShareOfInflows {
+  /**
+   * Share of all buyer money paid out to the creator, as `num / den` (0 ≤ share < 1).
+   * Not reduced to lowest terms — compare two shares by cross-multiplying.
+   */
+  readonly num: bigint;
+  readonly den: bigint;
+  /** How many releases it takes to sell the whole clog. */
+  readonly releases: bigint;
+}
+
+export interface ClogModelInput {
+  /** Total supply, in any unit — basis points (10000) or raw token units. */
+  readonly supply: bigint;
+  /** The clog allocation, in the same unit. */
+  readonly clog: bigint;
+  /** The most one release sells, in the same unit. */
+  readonly slice: bigint;
+  /** Defaults to `CLOG_MODEL_FLOW_MULTIPLE`. */
+  readonly flowMultiple?: bigint;
+}
+
+/**
+ * The share of buyer money a clog routes to the creator, as an exact fraction,
+ * or null when the model does not apply (a malformed input, or a release that
+ * would breach the floor). A zero clog captures nothing:
+ * `{ num: 0n, den: 1n, releases: 0n }`.
+ */
+export function clogShareOfInflows(input: ClogModelInput): ShareOfInflows | null {
+  const { supply, clog, slice } = input;
+  const flowMultiple = input.flowMultiple ?? CLOG_MODEL_FLOW_MULTIPLE;
+
+  if (supply <= 0n || clog < 0n || clog >= supply) return null;
+  if (clog === 0n) return { num: 0n, den: 1n, releases: 0n };
+  if (slice <= 0n || flowMultiple <= 0n) return null;
+
+  const x0 = supply - clog;
+  const k = x0 * x0; // q0 = x0 in units of p0
+  const buy = flowMultiple * slice;
+
+  // q = qn / qd, kept as an unreduced exact fraction.
+  let qn = x0;
+  let qd = 1n;
+  let remaining = clog;
+  let rounds = 0n;
+
+  while (remaining > 0n) {
+    if (rounds >= MAX_ROUNDS) return null;
+    rounds += 1n;
+
+    // Buyers spend: q ← q + B.
+    qn += buy * qd;
+
+    // The clog sells s tokens: q ← k·q / (k + s·q).
+    const sold = remaining < slice ? remaining : slice;
+    const nextN = k * qn;
+    const nextD = k * qd + sold * qn;
+
+    // Floor: q must not fall below q0 (= x0), i.e. nextN / nextD ≥ x0.
+    if (nextN < x0 * nextD) return null;
+
+    // Left unreduced. The fraction almost never reduces, and a gcd on numbers
+    // that grow a few dozen bits per round is what makes a 2,500-round type slow.
+    qn = nextN;
+    qd = nextD;
+    remaining -= sold;
+  }
+
+  // share = 1 − (q − q0) / (n·B) = (n·B·qd − (qn − x0·qd)) / (n·B·qd)
+  const inflow = rounds * buy;
+  const den = inflow * qd;
+  const num = den - (qn - x0 * qd);
+  return { num, den, releases: rounds };
+}
+
+/** The same model, stated in basis points of supply — the unit a launch type declares. */
+export function clogShareOfInflowsFromBps(
+  clogBps: bigint,
+  sliceBps: bigint,
+  flowMultiple: bigint = CLOG_MODEL_FLOW_MULTIPLE,
+): ShareOfInflows | null {
+  return clogShareOfInflows({ supply: BPS, clog: clogBps, slice: sliceBps, flowMultiple });
+}
+
+/** `num / den` scaled by `unit`, rounded half up. `num ≥ 0`, `den > 0`. */
+function roundHalfUp(num: bigint, den: bigint, unit: bigint): bigint {
+  return (num * unit * 2n + den) / (den * 2n);
+}
+
+/**
+ * Share of inflows, in basis points, for a clog of `clogBps` of supply sold in
+ * slices of `sliceBps` of supply.
+ *
+ * Pass the launch type's own `clogSliceBps` (from `getVariantAllocation`), not
+ * the policy table's 1%: the slice moves the answer (5% in 1% slices is 1649 bps;
+ * in the live 0.25% slices it is 1417 bps).
+ *
+ * @param clogBps      Clog allocation, bps of total supply.
+ * @param sliceBps     Per-release cap, bps of total supply.
+ * @param flowMultiple Buyer spend between releases, in slices at the launch
+ *                     price. The model's one assumption; defaults to
+ *                     `CLOG_MODEL_FLOW_MULTIPLE` (100).
+ * @returns Nearest basis point, rounded half up — the only rounding in the model
+ *          (use `clogShareOfInflows` for the exact fraction) — or null when the
+ *          model does not apply.
+ */
+export function clogInflowShareBps(
+  clogBps: bigint,
+  sliceBps: bigint,
+  flowMultiple: bigint = CLOG_MODEL_FLOW_MULTIPLE,
+): bigint | null {
+  const share = clogShareOfInflowsFromBps(clogBps, sliceBps, flowMultiple);
+  return share === null ? null : roundHalfUp(share.num, share.den, BPS);
+}
+
+/**
+ * What share of INFLOWS a clog routes to the creator, given its share of supply —
+ * AT THE POLICY TABLE'S 1% SLICE AND 0.1% RESOLUTION.
+ *
+ * @deprecated Kept for existing callers. It answers for the CLAUDE.md table's
+ * assumed slice, not for any real launch type's, so it overstates the live Sepolia
+ * Clog type (5%: 1650 here vs 1417 at its real 0.25% slice). Use
+ * `clogInflowShareBps(clogBps, allocation.clogSliceBps)`.
+ *
+ * Output is unchanged for the four table rows (500 → 1650, 1000 → 3710,
+ * 1500 → 5460, 2500 → 7500). It is now derived from the model rather than looked
+ * up, so any integer clog in [0, 10000) returns a value (a multiple of 10) where
+ * it used to return null; non-integer or out-of-range input still returns null.
+ */
+export function inflowShareBps(clogBps: number): number | null {
+  if (!Number.isSafeInteger(clogBps)) return null;
+  const share = clogShareOfInflowsFromBps(BigInt(clogBps), CLOG_TABLE_SLICE_BPS);
+  if (share === null) return null;
+  // Table resolution is 0.1% = 10 bps: round once at that resolution, then restate in bps.
+  return Number(roundHalfUp(share.num, share.den, BPS / 10n) * 10n);
+}