@peddles/sdk 0.2.0

package/src/deployments.generated.ts

@@ -0,0 +1,98 @@
+// GENERATED FILE — DO NOT EDIT.
+// Written by script/generate-deployments.mjs from contracts/deployments/<chainId>.json
+// and <chainId>-perp.json.
+// Re-run it after any deploy and commit the result.
+
+/** Every Peddles contract address the SDK knows, by chain id. */
+export const DEPLOYMENTS = {
+  4663: {
+    PeddlesClogVaultFactory: '0x1d2142699F1D818203738226240C605243a39b9e',
+    PeddlesFactoryV20: '0x51336A94B55Ad82D1099Dc82b27b151eDFfc1978',
+    PeddlesFeeForwarder: '0xc572A003d0Ab529da670a42177Fc583b03D5b026',
+    PeddlesFeeHook: '0xfe055282E3cD471A8b2cd922d31E75ECd3bBc0CC',
+    PeddlesHandleLauncher: '0x3720ca29D87E692000Ca71C56a56a3BA05B00CD1',
+    PeddlesHandlePotFactory: '0x2b5881c79a83C9EB17C67354F6737f3c9A120DE2',
+    PeddlesHolderRewardsFactory: '0xB22d6D7B1eC296AA79cbFf4ABE4992A726BE1978',
+    PeddlesLaunchOrchestratorV20: '0x81213e2cE27f03714143152aE5cf5c94094f1978',
+    PeddlesLiquidityActivationManager: '0xBE8d8999b53c5E5249feBafe5f505221F3e41978',
+    PeddlesNFTBondingGraduationOrchestratorV20: '0x6C5032DeDCc78b92b370C86a2aA0EA3AD0D71978',
+    PeddlesNFTFactory: '0x2e0029BeDCBb2f211Fd17EeBA8f40657cF6A1978',
+    PeddlesNftFeeDistributorFactory: '0x3081d5E69b7D12A330C9594C175F88EB77f31978',
+    PeddlesNftLiquidityReserve: '0x367F626775E22818C369BB3a276E3e9Fbc201978',
+    PeddlesNFTMarketplace: '0xC0374a0776449fE60dD1653C6421bEB41e911978',
+    PeddlesNftStockGraduationOrchestrator: '0x3DAd8D2B78C8a71f01600FDecA0b17af5F961978',
+    PeddlesPerpFactory: '0xCFA648281759C406E921F736c86ece2a9c4D1Fca',
+    PeddlesPerpHookDeployer: '0x3ab1848069cE7d19CD62ffB645292146cDd0139F',
+    PeddlesPerpTreasury: '0x2C322f48B2dD97f6c5050eDF5F349C7f70126dB5',
+    PeddlesRouteSwapRouter: '0xA4858047F9c7359CC0d9071598BFA74187739d8D',
+    PeddlesStockLaunchpad: '0x4b7Aa977eA4B95D9859D73e6bc922ecF2F881978',
+    PeddlesStockSwapRouter: '0x5A934c5eE47daa3b4562f9Dc9224bB00e9191978',
+    PeddlesStockVaultFactory: '0xa565E57046B51C4C1144b837A1871FF89c141978',
+    PeddlesTransferValidator: '0x2ADA0EA86925b5EbA1CF7B75e0d606C89b1B1978',
+    PeddlesV4LiquidityExecutor: '0xAB23BD1234AB1BCa48a97aB8e2baaFAaE7A21978',
+    PeddlesV4SwapRouter: '0xDd1F65380C9f7283A61FC489DCAceA352ee31978',
+    PeddlesVaultFactoryV20: '0xe6EE48916F87DD8E8Cab9D100a5E9717aE731978',
+    PeddlesVaultRegistry: '0xd322A44c4600dfDcF399Ceb7a32869e83d561978',
+  },
+  8453: {
+    PeddlesClogVaultFactory: '0x8563Aeec8C63d53BC8dfbE56FF9134a7b1e80503',
+    PeddlesFactoryV20: '0x90bD4d38F621529b4aD6480c221075B7317b1978',
+    PeddlesFeeForwarder: '0x77886951f19458B2FC27D4373553001A620264D3',
+    PeddlesFeeHook: '0xAB8E39207718f519865D6f0d52eFB31b231D40cc',
+    PeddlesFlywheel: '0x2E9366BF81d0D0ebA905927B55d3Fa3008891978',
+    PeddlesHandleLauncher: '0x265f0653aA62B30Fab11d0718D12CedE7965d7C4',
+    PeddlesHandlePotFactory: '0xC2575Cc3Eb3934C826Fa33FC9BA2e6DA8186D725',
+    PeddlesHolderRewardsFactory: '0xE4A89dCb02211409b50CEFd9B570E67dA2aD1978',
+    PeddlesLaunchOrchestratorV20: '0x7e7E62B41E447B6526E89D0AAAd7Cac9FB9f1978',
+    PeddlesLiquidityActivationManager: '0xa8bfd83d21eec43F9a984C6B13a31Ce1df191978',
+    PeddlesNFTBondingGraduationOrchestratorV20: '0xB7bB0f25B1AE59adcAa2787C68cd50296d2B1978',
+    PeddlesNFTFactory: '0xd111413B91b0E31865464658071099779e2C1978',
+    PeddlesNftFeeDistributorFactory: '0x9B0c155e7248706860c9707c2a8f41A0a2281978',
+    PeddlesNftLiquidityReserve: '0x444C34FF8503eA088a36792659D7c34D7F931978',
+    PeddlesNFTMarketplace: '0x5362a7DE96E8b3474Aef1a0fE6F6e2427Bd81978',
+    PeddlesNftStockGraduationOrchestrator: '0xD6d41a5029EC7F78886C135A71A9c85e96781978',
+    PeddlesPerpFactory: '0x71a8EF2288fFdB3b1d546C33a16F0d4104E11488',
+    PeddlesPerpHookDeployer: '0x9122dAd755B6F8c1DB5F2B7c494580169fB327F2',
+    PeddlesPerpTreasury: '0xDB77eA86006E530D25789F2cf2aeB7bd2C7c3745',
+    PeddlesRouteSwapRouter: '0x8f04A804Ba989d38A68D93eb8679d3a967f2b079',
+    PeddlesStockLaunchpad: '0x680805FBd0D6225d0bE4E12A2B73b2Ed83a31978',
+    PeddlesStockSwapRouter: '0xd150B1E102493e4F35A1e95DdA80948C0e581978',
+    PeddlesStockVaultFactory: '0x5EF74DFc6Dfd9e5dAb314Df5747AC4E117e41978',
+    PeddlesToken: '0xCF2Be52981b5BD563C268a0e2b17D50B53e21978',
+    PeddlesTransferValidator: '0xD1390f3E4741963A7eEd1E53163a1B09c97e1978',
+    PeddlesV4LiquidityExecutor: '0x4Ca94531420F0e4f5a612475c8c4E35E9c8d1978',
+    PeddlesV4SwapRouter: '0xbf7A709cBf71b303B856126D3aEb5051a07c1978',
+    PeddlesVaultFactoryV20: '0xD4fe62B8cd5a7e07fF09D6D1151fA5BC8A771978',
+    PeddlesVaultRegistry: '0xb390c4A83D8B308b378250a59F273A7c9aDF1978',
+  },
+} as const;
+
+/**
+ * The perp launchpad on each chain that has one (from contracts/deployments/<chainId>-perp.json).
+ * `baseCandidates` are the bases the deploy whitelisted — CANDIDATES only: whether a base is
+ * allowed, and on what curve, is read live from `PeddlesPerpFactory.bases(base)`.
+ */
+export const PERP_DEPLOYMENTS = {
+  4663: {
+    PeddlesPerpFactory: '0xCFA648281759C406E921F736c86ece2a9c4D1Fca',
+    PeddlesPerpHookDeployer: '0x3ab1848069cE7d19CD62ffB645292146cDd0139F',
+    PeddlesPerpTreasury: '0x2C322f48B2dD97f6c5050eDF5F349C7f70126dB5',
+    hookCodePointer: '0xf97907D6AA1Ae3D3Ec3247eEfA998C8D6BE78605',
+    baseCandidates: {
+      WETH: '0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73',
+    },
+  },
+  8453: {
+    PeddlesPerpFactory: '0x71a8EF2288fFdB3b1d546C33a16F0d4104E11488',
+    PeddlesPerpHookDeployer: '0x9122dAd755B6F8c1DB5F2B7c494580169fB327F2',
+    PeddlesPerpTreasury: '0xDB77eA86006E530D25789F2cf2aeB7bd2C7c3745',
+    hookCodePointer: '0xDAE55090fF0ffb81E3da33C79950DF7Ef78379aA',
+    baseCandidates: {
+      WETH: '0x4200000000000000000000000000000000000006',
+    },
+  },
+} as const;
+
+export type KnownChainId = keyof typeof DEPLOYMENTS;
+export type PerpChainId = keyof typeof PERP_DEPLOYMENTS;
+export type ContractName<C extends KnownChainId = KnownChainId> = keyof (typeof DEPLOYMENTS)[C];

package/src/deployments.ts

@@ -0,0 +1,60 @@
+import { DEPLOYMENTS, type KnownChainId, type ContractName } from './deployments.generated.js';
+
+export { DEPLOYMENTS };
+export type { KnownChainId, ContractName };
+
+/** Thrown when the SDK is asked about a chain it ships no address book for. */
+export class UnknownChainError extends Error {
+  readonly chainId: number;
+  constructor(chainId: number) {
+    super(
+      `Peddles SDK has no deployment for chain ${chainId}. ` +
+        `Known chains: ${Object.keys(DEPLOYMENTS).join(', ')}. ` +
+        `Pass an explicit address map if you are pointing at a private deployment.`,
+    );
+    this.name = 'UnknownChainError';
+    this.chainId = chainId;
+  }
+}
+
+/** Thrown when a chain is known but does not carry the contract being asked for. */
+export class UnknownContractError extends Error {
+  constructor(chainId: number, name: string) {
+    super(
+      `Peddles SDK has no address for ${name} on chain ${chainId}. ` +
+        `That deployment may predate the contract.`,
+    );
+    this.name = 'UnknownContractError';
+  }
+}
+
+export function isKnownChain(chainId: number): chainId is KnownChainId {
+  return Object.prototype.hasOwnProperty.call(DEPLOYMENTS, chainId);
+}
+
+/**
+ * The address book for one chain.
+ *
+ * FAILS CLOSED, ALWAYS. An unknown chain throws rather than returning a default
+ * or an empty map, and a missing contract throws rather than returning
+ * `undefined` or the zero address. Both of those alternatives look like a
+ * working call right up until a transaction is signed against nothing.
+ *
+ * This is not hypothetical in this codebase: every address changed in a single
+ * redeploy, and one stale copy of this list had the API quoting a launchpad that
+ * no longer existed — an error that surfaced as "neither leg is a launched coin"
+ * rather than as a missing address.
+ */
+export function deploymentFor(chainId: number): Readonly<Record<string, `0x${string}`>> {
+  if (!isKnownChain(chainId)) throw new UnknownChainError(chainId);
+  return DEPLOYMENTS[chainId] as Readonly<Record<string, `0x${string}`>>;
+}
+
+/** One address, or a throw. Never a default, never the zero address. */
+export function addressOf(chainId: number, name: string): `0x${string}` {
+  const book = deploymentFor(chainId);
+  // Own properties only: `book['constructor']` would otherwise return a function.
+  const found = Object.prototype.hasOwnProperty.call(book, name) ? book[name] : undefined;
+  if (!found || /^0x0{40}$/.test(found)) throw new UnknownContractError(chainId, name);
+  return found;
+}

package/src/feeSplit.ts

@@ -0,0 +1,76 @@
+/**
+ * How one charged fee divides — the exact arithmetic `PeddlesFeeHook._book` runs.
+ *
+ * IMPORT-FREE on purpose, like `clogInflow.ts`: it is pure bigint maths with no
+ * runtime, so a UI, an indexer or a test can use it without pulling in viem.
+ *
+ * THE MODEL (fixed at launch, never changed afterwards):
+ *
+ *   creatorTaxBps       the ALL-IN rate a trader pays, 100..1000 (1%..10%)
+ *   excessToCreatorBps  the creator's share of everything ABOVE the two fixed
+ *                       0.50% legs, 0..10000; the rest of that excess is holders'
+ *
+ *   platform    = fee × 50 / creatorTaxBps                       (floored)
+ *   creatorBase = fee × 50 / creatorTaxBps                       (floored)
+ *   excess      = fee − platform − creatorBase
+ *   creator     = creatorBase + excess × excessToCreatorBps / 10000   (floored)
+ *   holders     = fee − platform − creator                      (the remainder)
+ *
+ * Every floor lands its dust with holders, so `platform + creator + holders`
+ * equals `fee` exactly; at `excessToCreatorBps == 10000` the holder leg is 0.
+ *
+ * `fee` is what the hook CHARGED, in the pool's quote asset. It is not the trade
+ * size: the hook charges `gross × creatorTaxBps / 10000` (floored) on an exact-in
+ * trade and grosses up an exact-out one. During a pool's opening window the hook
+ * uses a different, fixed split (½ liquidity / ¼ creator / ¼ platform) that this
+ * function does not model.
+ */
+
+/** `PeddlesFeeHook.PLATFORM_FEE_BPS`. */
+export const PLATFORM_FEE_BPS = 50;
+/** `PeddlesFeeHook.CREATOR_FEE_BPS`. */
+export const CREATOR_FEE_BPS = 50;
+/** `PeddlesFeeHook.MIN_CREATOR_TAX_BPS` — the two fixed legs added together. */
+export const MIN_CREATOR_TAX_BPS = PLATFORM_FEE_BPS + CREATOR_FEE_BPS;
+/** `PeddlesFeeHook.MAX_CREATOR_TAX_BPS`. */
+export const MAX_CREATOR_TAX_BPS = 1000;
+/** Basis-point denominator. */
+export const BPS = 10_000;
+/** `PeddlesFeeHook.MAX_FEE_AMOUNT` — the largest fee one accrual can represent (int128 max). */
+export const MAX_FEE_AMOUNT = (1n << 127n) - 1n;
+
+/** One fee, divided. Base units of the pool's quote asset. */
+export interface FeeSplit {
+  readonly platform: bigint;
+  readonly creator: bigint;
+  readonly holders: bigint;
+}
+
+function assertBps(label: string, value: number, min: number, max: number): void {
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new RangeError(`${label} must be an integer in [${min}, ${max}], got ${String(value)}`);
+  }
+}
+
+/**
+ * Divide a charged fee between platform, creator and holders.
+ *
+ * Throws `RangeError` for terms `registerPool` would refuse, and for a fee the
+ * hook would not charge at all (negative, or above `MAX_FEE_AMOUNT`). Returning a
+ * split for either would describe a charge that cannot happen.
+ */
+export function feeSplit(creatorTaxBps: number, excessToCreatorBps: number, fee: bigint): FeeSplit {
+  assertBps('creatorTaxBps', creatorTaxBps, MIN_CREATOR_TAX_BPS, MAX_CREATOR_TAX_BPS);
+  assertBps('excessToCreatorBps', excessToCreatorBps, 0, BPS);
+  if (typeof fee !== 'bigint') throw new TypeError('fee must be a bigint in base units');
+  if (fee < 0n) throw new RangeError(`fee must not be negative, got ${fee}`);
+  if (fee > MAX_FEE_AMOUNT) throw new RangeError(`fee ${fee} exceeds MAX_FEE_AMOUNT; the hook charges nothing`);
+
+  const total = BigInt(creatorTaxBps);
+  const platform = (fee * BigInt(PLATFORM_FEE_BPS)) / total;
+  const creatorBase = (fee * BigInt(CREATOR_FEE_BPS)) / total;
+  const excess = fee - platform - creatorBase;
+  const creator = creatorBase + (excess * BigInt(excessToCreatorBps)) / BigInt(BPS);
+  const holders = fee - platform - creator;
+  return { platform, creator, holders };
+}

package/src/feeTerms.ts

@@ -0,0 +1,137 @@
+import type { ReadClient } from './client.js';
+import type { Address, Hex } from 'viem';
+import { feeHookAbi, liquidityExecutorAbi, stockLaunchpadAbi } from './abis.js';
+import { addressOf } from './deployments.js';
+
+/**
+ * A launch pool's permanent terms, read from `PeddlesFeeHook`.
+ *
+ * Every launch pool — stock-paired, WETH-paired, Clog, and both NFT graduations —
+ * is registered with the hook once, at launch, and nothing can change these
+ * afterwards. What a buyer pays is `creatorTaxBps`; `excessToCreatorBps` decides
+ * who receives the part above the fixed 1% (creator vs holders).
+ */
+export interface PoolTerms {
+  readonly poolId: Hex;
+  readonly token: Address;
+  /** The asset the tax is charged in, and the asset holder rewards pay out in. */
+  readonly quote: Address;
+  readonly creator: Address;
+  /** All-in tax a trader pays, in bps (100..1000). Excludes any opening-window premium. */
+  readonly creatorTaxBps: number;
+  /** Creator's share of the tax above the fixed 1%, in bps (0..10000). The rest goes to holders. */
+  readonly excessToCreatorBps: number;
+  /** The pool's `PeddlesHolderRewards` distributor. */
+  readonly rewards: Address;
+}
+
+/** Why `getPoolTerms` could not answer. It never substitutes a default. */
+export type PoolTermsFailure = 'legacy-fee-hook' | 'not-registered' | 'ambiguous';
+
+export class PoolTermsUnavailableError extends Error {
+  readonly reason: PoolTermsFailure;
+  constructor(reason: PoolTermsFailure, message: string) {
+    super(message);
+    this.name = 'PoolTermsUnavailableError';
+    this.reason = reason;
+  }
+}
+
+const ZERO_ID = /^0x0{64}$/i;
+
+interface RawPoolConfig {
+  quote: Address;
+  creatorTaxBps: number;
+  excessToCreatorBps: number;
+  registered: boolean;
+  token: Address;
+  creator: Address;
+  rewards: Address;
+}
+
+/**
+ * The launch terms of `token`'s pool on `chainId`.
+ *
+ * FINDING THE POOL. The hook is keyed by pool id, not by token, so the id comes
+ * from the contract that created the pool: `PeddlesStockLaunchpad.coins(token)`
+ * for stock-paired coins (including NFT stock graduations), and
+ * `PeddlesV4LiquidityExecutor.poolIdFor(token)` for WETH-paired ones. The hook's
+ * own record must then name this token and be registered — anything else throws.
+ *
+ * FAILS CLOSED, the same as the address book:
+ *   - a deployment whose hook predates the fixed-terms model throws
+ *     (`legacy-fee-hook`) — its third config field meant something else, so
+ *     decoding it with this ABI would return a plausible, wrong number;
+ *   - a token with no registered launch pool throws (`not-registered`).
+ */
+export async function getPoolTerms(client: ReadClient, chainId: number, token: Address): Promise<PoolTerms> {
+  const hook = addressOf(chainId, 'PeddlesFeeHook');
+  const launchpad = addressOf(chainId, 'PeddlesStockLaunchpad');
+  const executor = addressOf(chainId, 'PeddlesV4LiquidityExecutor');
+
+  const [factory, coin, wethPoolId] = await client.multicall({
+    allowFailure: true,
+    contracts: [
+      { address: hook, abi: feeHookAbi, functionName: 'holderRewardsFactory' },
+      { address: launchpad, abi: stockLaunchpadAbi, functionName: 'coins', args: [token] },
+      { address: executor, abi: liquidityExecutorAbi, functionName: 'poolIdFor', args: [token] },
+    ],
+  });
+
+  // `holderRewardsFactory` exists only on the fixed-terms hook. A hook that does not
+  // answer it is the previous model, not a transient failure to be guessed around.
+  if (factory.status !== 'success' || /^0x0{40}$/i.test(factory.result as string)) {
+    throw new PoolTermsUnavailableError(
+      'legacy-fee-hook',
+      `PeddlesFeeHook ${hook} on chain ${chainId} does not expose holderRewardsFactory(); ` +
+        `this deployment predates fixed launch terms, so they cannot be read from it.`,
+    );
+  }
+
+  const candidates: Hex[] = [];
+  if (coin.status === 'success') {
+    const poolId = (coin.result as readonly unknown[])[2] as Hex;
+    if (!ZERO_ID.test(poolId)) candidates.push(poolId);
+  }
+  if (wethPoolId.status === 'success' && !ZERO_ID.test(wethPoolId.result as Hex)) {
+    candidates.push(wethPoolId.result as Hex);
+  }
+
+  const configs =
+    candidates.length === 0
+      ? []
+      : await client.multicall({
+          allowFailure: false,
+          contracts: candidates.map(
+            (poolId) => ({ address: hook, abi: feeHookAbi, functionName: 'poolConfig', args: [poolId] }) as const,
+          ),
+        });
+
+  const matches = candidates
+    .map((poolId, i) => ({ poolId, config: configs[i] as unknown as RawPoolConfig }))
+    .filter(({ config }) => config.registered && config.token.toLowerCase() === token.toLowerCase());
+
+  if (matches.length === 0) {
+    throw new PoolTermsUnavailableError(
+      'not-registered',
+      `No registered Peddles launch pool for ${token} on chain ${chainId}.`,
+    );
+  }
+  if (matches.length > 1) {
+    throw new PoolTermsUnavailableError(
+      'ambiguous',
+      `${token} has more than one registered launch pool on chain ${chainId}; refusing to pick one.`,
+    );
+  }
+
+  const { poolId, config } = matches[0] as { poolId: Hex; config: RawPoolConfig };
+  return {
+    poolId,
+    token: config.token,
+    quote: config.quote,
+    creator: config.creator,
+    creatorTaxBps: Number(config.creatorTaxBps),
+    excessToCreatorBps: Number(config.excessToCreatorBps),
+    rewards: config.rewards,
+  };
+}

package/src/index.ts

@@ -0,0 +1,233 @@
+import type { ReadClient } from './client.js';
+/**
+ * @peddles/sdk — read and build against Peddles launches.
+ *
+ * ONE PACKAGE, SIX ENTRY POINTS. Take only what you import:
+ *
+ *   @peddles/sdk               this file — chain resolution, launch reads, pool terms
+ *   @peddles/sdk/abis          ABI fragments alone, no runtime
+ *   @peddles/sdk/clog          the Clog launch type
+ *   @peddles/sdk/deployments   the address book
+ *   @peddles/sdk/launch        launch calldata builders, salts, revert decoding
+ *   @peddles/sdk/perps         the perp launchpad (PeddlesPerpFactory)
+ *
+ * `viem` is a PEER dependency, not a bundled one: an integrator already has a
+ * client, and two copies of viem in a bundle is both bloat and a source of
+ * "instance is not a PublicClient" errors that are miserable to diagnose.
+ *
+ * WHAT IS DELIBERATELY ABSENT. This package exposes reads and calldata, not
+ * infrastructure. `ContractService`, `WalletService` and the log-source used by
+ * the indexer stay internal to the monorepo: publishing them would freeze this
+ * project's internals as public API and commit it to supporting them.
+ */
+import type { Address, Hex } from 'viem';
+import { encodeAbiParameters, getContractAddress, keccak256 } from 'viem';
+import { erc20Abi, factoryAbi } from './abis.js';
+import { addressOf, deploymentFor, isKnownChain, UnknownChainError } from './deployments.js';
+
+export {
+  DEPLOYMENTS,
+  addressOf,
+  deploymentFor,
+  isKnownChain,
+  UnknownChainError,
+  UnknownContractError,
+} from './deployments.js';
+export type { KnownChainId, ContractName } from './deployments.js';
+export type { ReadClient } from './client.js';
+
+export {
+  getVariantAllocation,
+  getClogVault,
+  getClogState,
+  inflowShareBps,
+  isReleaseReady,
+  CLOG_MODEL_FLOW_MULTIPLE,
+  CLOG_TABLE_SLICE_BPS,
+  clogShareOfInflows,
+  clogShareOfInflowsFromBps,
+  clogInflowShareBps,
+} from './clog.js';
+export type { VariantAllocation, ClogState, ShareOfInflows, ClogModelInput } from './clog.js';
+
+export {
+  factoryAbi,
+  clogVaultAbi,
+  clogVaultFactoryAbi,
+  erc20Abi,
+  tokenV20Abi,
+  feeHookAbi,
+  stockLaunchpadAbi,
+  holderRewardsAbi,
+  nftFactoryAbi,
+  nftCollectionAbi,
+  nftFeeDistributorFactoryAbi,
+  nftFeeDistributorAbi,
+  nftBondingGraduationOrchestratorAbi,
+  nftStockGraduationOrchestratorAbi,
+  liquidityExecutorAbi,
+} from './abis.js';
+
+export {
+  relayParamsHash,
+  stockGraduationOptInRequest,
+  graduateToStockWithTermsRequest,
+  graduateAndBuyRequest,
+  predictDistributor,
+  getHolderCommitment,
+  getDistributorState,
+  holderClaimable,
+} from './artDex.js';
+export type { RelayParams, StockTermsLaunch, HolderCommitment, DistributorState, HolderClaimable } from './artDex.js';
+
+export { getPoolTerms, PoolTermsUnavailableError } from './feeTerms.js';
+export type { PoolTerms, PoolTermsFailure } from './feeTerms.js';
+
+export {
+  feeSplit,
+  PLATFORM_FEE_BPS,
+  CREATOR_FEE_BPS,
+  MIN_CREATOR_TAX_BPS,
+  MAX_CREATOR_TAX_BPS,
+  MAX_FEE_AMOUNT,
+} from './feeSplit.js';
+export type { FeeSplit } from './feeSplit.js';
+
+/** A launched token, as the chain describes it. */
+export interface TokenInfo {
+  readonly address: Address;
+  readonly name: string;
+  readonly symbol: string;
+  readonly decimals: number;
+  readonly totalSupply: bigint;
+}
+
+/**
+ * Identity and supply, read from the token itself.
+ *
+ * `decimals` travels with `totalSupply` on purpose. Every amount this SDK
+ * returns is a raw `bigint` in base units and MUST be formatted against its own
+ * decimals — never assume 18, and never route a token amount through a JS
+ * `number`, which loses precision above 2^53 and will silently mis-price a
+ * large-supply token.
+ */
+export async function getTokenInfo(client: ReadClient, token: Address): Promise<TokenInfo> {
+  const base = { address: token, abi: erc20Abi } as const;
+  const [name, symbol, decimals, totalSupply] = await client.multicall({
+    allowFailure: false,
+    contracts: [
+      { ...base, functionName: 'name' },
+      { ...base, functionName: 'symbol' },
+      { ...base, functionName: 'decimals' },
+      { ...base, functionName: 'totalSupply' },
+    ],
+  });
+  return {
+    address: token,
+    name: name as string,
+    symbol: symbol as string,
+    decimals: decimals as number,
+    totalSupply: totalSupply as bigint,
+  };
+}
+
+/**
+ * Whether a launch type can be launched on this chain right now.
+ *
+ * Ask before offering one. A variant with no code registered, or one an owner
+ * has retired, reports false — and a UI that offers it anyway sends a creator
+ * into a transaction that cannot succeed.
+ */
+export async function isVariantSupported(
+  client: ReadClient,
+  chainId: number,
+  variant: number,
+): Promise<boolean> {
+  return (await client.readContract({
+    address: addressOf(chainId, 'PeddlesFactoryV20'),
+    abi: factoryAbi,
+    functionName: 'isVariantSupported',
+    args: [variant],
+  })) as boolean;
+}
+
+/** Everything `PeddlesFactoryV20` hashes into a token's CREATE2 address. */
+export interface TokenAddressInput {
+  readonly factory: Address;
+  readonly variant: number;
+  /** The launcher that calls the factory (e.g. the orchestrator), not the end user. */
+  readonly sender: Address;
+  readonly salt: Hex;
+  /** keccak256 of the variant's creation code, as the factory reports it. */
+  readonly creationCodeHash: Hex;
+}
+
+/**
+ * The CREATE2 address, computed locally — the exact formula the factory uses:
+ *
+ *   boundSalt = keccak256(abi.encode(uint8 variant, address sender, bytes32 salt))
+ *   address   = keccak256(0xff ‖ factory ‖ boundSalt ‖ creationCodeHash)[12:]
+ *
+ * `creationCodeHash` is deliberately an input, not a constant shipped here. For
+ * the plain token it is the factory's immutable `TOKEN_CREATION_CODE_HASH`
+ * (keccak256 of `type(PeddlesTokenV20).creationCode` in the build that
+ * deployed it), and for a registered variant the hash stored at registration.
+ * Any recompile moves it, so the deployed factory is the only reliable source —
+ * read it with `predictTokenAddress`, or pass one you read yourself.
+ */
+export function computeTokenAddress(input: TokenAddressInput): Address {
+  const boundSalt = keccak256(
+    encodeAbiParameters(
+      [{ type: 'uint8' }, { type: 'address' }, { type: 'bytes32' }],
+      [input.variant, input.sender, input.salt],
+    ),
+  );
+  return getContractAddress({
+    opcode: 'CREATE2',
+    from: input.factory,
+    salt: boundSalt,
+    bytecodeHash: input.creationCodeHash,
+  });
+}
+
+/**
+ * The CREATE2 address a launch will deploy to, before it is launched.
+ *
+ * THE VARIANT IS PART OF THE ADDRESS: the factory binds
+ * `keccak256(abi.encode(variant, sender, salt))`, so the same salt under two
+ * launch types produces two different addresses. Passing the wrong variant here
+ * yields an address the factory will never deploy to.
+ *
+ * The creation-code hash is read from the deployed factory (`variantInfo`, which
+ * returns `TOKEN_CREATION_CODE_HASH` for the plain token), never assumed. An
+ * unknown variant throws, as `getPeddlesAddress` does; a retired one still
+ * resolves, so an address quoted before retirement stays recoverable.
+ */
+export async function predictTokenAddress(
+  client: ReadClient,
+  chainId: number,
+  variant: number,
+  sender: Address,
+  salt: Hex,
+): Promise<Address> {
+  const factory = addressOf(chainId, 'PeddlesFactoryV20');
+  const [, creationCodeHash] = (await client.readContract({
+    address: factory,
+    abi: factoryAbi,
+    functionName: 'variantInfo',
+    args: [variant],
+  })) as readonly [Address, Hex, boolean];
+  if (/^0x0{64}$/i.test(creationCodeHash)) {
+    throw new Error(`PeddlesFactoryV20 on chain ${chainId} has no launch type ${variant}.`);
+  }
+  return computeTokenAddress({ factory, variant, sender, salt, creationCodeHash });
+}
+
+/** Chains this build ships an address book for. */
+export function supportedChains(): number[] {
+  return Object.keys(DEPLOYMENTS_KEYS).map(Number);
+}
+
+// Imported lazily-shaped to keep the public surface honest: `supportedChains`
+// reads the same generated map every other entry point does.
+import { DEPLOYMENTS as DEPLOYMENTS_KEYS } from './deployments.generated.js';