@masterpeach/launchpad-sdk 0.0.0-experimental-20260818121657

package/dist/index.d.cts

@@ -0,0 +1,1273 @@
+import { Address, Hex, PublicClient, BlockTag, WalletClient, TransactionReceipt, Hash } from 'viem';
+import { S as SdkTransactionResult } from './transaction-BiLcoXyx.cjs';
+
+/**
+ * Addresses of a single, version-scoped Launchpad deployment. Every field is scoped to one
+ * `chainId + portal`; a Portal redeployment is a new deployment, never an in-place upgrade.
+ * The bonding curve, migrator, and future DEX router are distinct modules and must not be
+ * conflated into a single "router" slot.
+ */
+interface LaunchpadContracts {
+    readonly portal: Address;
+    readonly tokenFactory: Address;
+    readonly curve: Address;
+    readonly migrator: Address;
+    readonly liquidityLocker: Address;
+    readonly quoteToken: Address;
+    readonly v3Factory?: Address;
+    readonly positionManager?: Address;
+    /** Only configured once a graduated-execution router adapter has been audited. */
+    readonly dexRouter?: Address;
+}
+/**
+ * A Launchpad protocol deployment traceable to an exact contract revision. The runtime code hash
+ * and commits let {@link verifyLaunchpadDeployment} prove the registered addresses match on-chain
+ * state before any read or write is trusted.
+ */
+interface LaunchpadDeployment {
+    readonly chainId: number;
+    readonly contractVersion: string;
+    readonly contracts: LaunchpadContracts;
+    readonly deploymentBlock: bigint;
+    readonly artifactCommit: string;
+    readonly sourceCommit: string;
+    readonly portalRuntimeCodeHash: Hex;
+}
+type LaunchpadDeploymentRegistry = Readonly<Record<number, LaunchpadDeployment>>;
+/**
+ * Raised when supplied deployment material fails structural validation. Mirrors the plain-`Error`
+ * shape of `InvalidLendingDomainError` and `InvalidLaunchpadChainConfigError`; chain resolution
+ * reuses the shared `UnsupportedChainError` instead.
+ */
+declare class InvalidLaunchpadDeploymentError extends Error {
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+/** Validates, normalizes, and deep-freezes a caller-supplied Launchpad deployment. */
+declare function defineLaunchpadDeployment(input: LaunchpadDeployment): Readonly<LaunchpadDeployment>;
+/**
+ * Validates and freezes a chainId-keyed deployment registry, rejecting any entry whose key does
+ * not match its own `chainId`.
+ */
+declare function defineLaunchpadDeploymentRegistry(input: Readonly<Record<number, LaunchpadDeployment>>): LaunchpadDeploymentRegistry;
+/**
+ * Built-in registry of production Launchpad deployments. It stays empty until a deployment has
+ * passed RPC bytecode and binding verification; testnet material is exported separately as an
+ * explicitly named development configuration.
+ */
+declare const launchpadDeploymentRegistry: LaunchpadDeploymentRegistry;
+/** Resolves a verified deployment or throws {@link UnsupportedChainError}. */
+declare function resolveLaunchpadDeployment(registry: LaunchpadDeploymentRegistry, chainId: number): Readonly<LaunchpadDeployment>;
+
+/**
+ * Block selector threaded through every read so a page can pin token state, quotes, balances, and
+ * allowances to one block instead of stitching together values from different heights.
+ */
+interface LaunchpadReadOptions {
+    readonly blockNumber?: bigint;
+    readonly blockTag?: BlockTag;
+}
+/** Public-client scope for a single verified deployment. */
+interface LaunchpadActionContext {
+    readonly publicClient: PublicClient;
+    readonly deployment: LaunchpadDeployment;
+}
+/** Adds the signer required for write paths. Chain agreement is re-checked at call time. */
+interface LaunchpadWriteActionContext extends LaunchpadActionContext {
+    readonly walletClient: WalletClient;
+}
+/** Chain-scoped ERC-20 asset reference. */
+interface LaunchpadAssetRef {
+    readonly address: Address;
+}
+
+/**
+ * Stable lifecycle phase. Maps `Portal.TokenState.status` (`INVALID=0`, `TRADING=1`,
+ * `MIGRATING=2`, `DEX=3`) onto names that do not leak the raw enum ordering to consumers.
+ */
+type LaunchpadPhase = "invalid" | "bonding" | "migrating" | "graduated";
+/**
+ * Token-level pause state. `Portal.setTokenPause` uses `0=active`, `1=buy paused (sell allowed)`,
+ * `2=all curve trades paused`.
+ */
+type LaunchpadPauseMode = "active" | "buyPaused" | "tradingPaused";
+/** Chain-scoped token state with every amount expressed as `bigint`. */
+interface LaunchpadTokenState {
+    readonly id: LaunchpadTokenId;
+    readonly phase: LaunchpadPhase;
+    readonly tokenVersion: number;
+    readonly curveId: number;
+    readonly migratorId: number;
+    readonly quoteReserve: bigint;
+    readonly circulatingSupply: bigint;
+    readonly creator: Address;
+    /** Absent while the token is `invalid`, or whenever the Portal reports the zero address. */
+    readonly dexPool?: Address;
+    readonly launchBlock: bigint;
+    readonly protectionBlocks: number;
+    readonly pauseMode: LaunchpadPauseMode;
+}
+/**
+ * Result of `Portal.quoteBuy`. `quoteSpent` may be less than the requested input when the buy
+ * reaches the graduation threshold, so approvals and UI must follow `quoteSpent`, not user input.
+ */
+interface BuyQuote {
+    readonly tokenOut: bigint;
+    readonly quoteSpent: bigint;
+    readonly fee: bigint;
+    readonly reachesGraduation: boolean;
+}
+/** Result of `Portal.quoteSell`. `quoteOut` is already net of the trade fee. */
+interface SellQuote {
+    readonly quoteOut: bigint;
+    readonly fee: bigint;
+}
+/** Slippage tolerance in basis points. Validated against a hard 10% ceiling. */
+interface Slippage {
+    readonly bps: number;
+}
+/**
+ * Bonding-curve reference price. This is always the curve formula's output, never an executable
+ * quote, and it does not become a live V3 pool price after graduation — hence the explicit
+ * `source` and the `phase` observed at read time.
+ */
+interface LaunchpadPrice {
+    readonly valueWad: bigint;
+    readonly source: "bondingCurveReference";
+    readonly phase: LaunchpadPhase;
+}
+/** Why a curve trade is currently rejected, or `undefined` when trading is available. */
+type LaunchpadTradeBlockedReason = "invalidToken" | "protocolPaused" | "buyPaused" | "tradingPaused" | "launchBlock" | "migrating" | "graduated";
+/**
+ * Everything a UI needs to render trade availability without re-deriving protection rules:
+ * the current phase, pause state, the fee that applies at `blockNumber`, and the next block at
+ * which trading becomes possible.
+ */
+interface LaunchpadTradeAvailability {
+    readonly phase: LaunchpadPhase;
+    readonly protocolPaused: boolean;
+    readonly pauseMode: LaunchpadPauseMode;
+    readonly canBuy: boolean;
+    readonly canSell: boolean;
+    readonly feeBps: number;
+    readonly blockNumber: bigint;
+    /** Present while inside the launch-block trading ban. */
+    readonly nextTradableBlock?: bigint;
+    readonly blockedReason?: LaunchpadTradeBlockedReason;
+}
+/**
+ * A graduated token's V3 liquidity position, permanently held by the Locker.
+ *
+ * `tokenId` is the Uniswap V3 position NFT id, not a token address. `token0`/`token1` follow V3's
+ * address ordering, so which one is the launched token depends on how it sorts against the quote
+ * token — never assume a fixed slot.
+ */
+interface LaunchpadLockedPosition {
+    readonly tokenId: bigint;
+    readonly token0: Address;
+    readonly token1: Address;
+    readonly creator: Address;
+    /** Platform share of collected fees, in basis points. The remainder credits the creator. */
+    readonly platformFeeBps: number;
+}
+/**
+ * A previewed CREATE2 token address.
+ *
+ * Valid only while `creatorNonce` is still the creator's current nonce — it increments on every
+ * successful creation, so launching any token invalidates an earlier prediction.
+ */
+interface PredictedLaunchpadToken {
+    readonly address: Address;
+    readonly creator: Address;
+    /** Portal nonce this prediction is bound to. */
+    readonly creatorNonce: bigint;
+    readonly userSalt: Hex;
+    /** The derived factory salt, exposed for verification against the chain. */
+    readonly salt: Hex;
+}
+/** On-chain name, symbol, and decimals for a token, read together at one block. */
+interface LaunchpadErc20Metadata {
+    readonly address: Address;
+    readonly name: string;
+    readonly symbol: string;
+    readonly decimals: number;
+}
+
+/** Canonical identifier for a Launchpad token. Addresses alone are not cross-chain identifiers. */
+interface LaunchpadTokenId {
+    readonly chainId: number;
+    readonly address: Address;
+}
+type LaunchpadCapability = "create" | "bondingTrade" | "graduatedTrade" | "antiFarmer" | "earlySellTax" | "rewards" | "referral";
+interface LaunchpadQuoteTokenConfig {
+    readonly address: Address;
+    readonly decimals: number;
+    readonly symbol: string;
+}
+/**
+ * Per-chain network and product metadata for the ABI-neutral adapter client. `deployment` is the
+ * same verified {@link LaunchpadDeployment} the typed `LaunchpadPortalClient` uses — there is no
+ * separate, looser address shape here. This keeps the bonding curve, migrator, and any future DEX
+ * router as distinct, named module slots instead of collapsing them into one ambiguous "router".
+ */
+interface LaunchpadChainConfig {
+    readonly slug: string;
+    readonly chainId: number;
+    readonly family: "evm";
+    readonly nativeCurrency: {
+        readonly symbol: string;
+        readonly decimals: number;
+    };
+    readonly rpcUrls: readonly string[];
+    readonly explorerUrl: string;
+    readonly apiBaseUrl: string;
+    readonly realtimeUrl: string;
+    readonly deployment: LaunchpadDeployment;
+    readonly quoteTokens: readonly LaunchpadQuoteTokenConfig[];
+    readonly capabilities: Readonly<Record<LaunchpadCapability, boolean>>;
+    readonly confirmations: number;
+}
+type LaunchpadChainRegistry = Readonly<Record<number, LaunchpadChainConfig>>;
+/**
+ * ABI-neutral request passed to a contract adapter. The operation and argument shape become typed
+ * only after the Launchpad contracts are delivered and their public interface is frozen.
+ */
+interface LaunchpadReadRequest {
+    readonly operation: string;
+    readonly args?: unknown;
+}
+interface LaunchpadWriteRequest extends LaunchpadReadRequest {
+    readonly requiredCapability: LaunchpadCapability;
+}
+interface LaunchpadReadContext {
+    readonly chain: LaunchpadChainConfig;
+    readonly publicClient: PublicClient;
+}
+interface LaunchpadWriteContext extends LaunchpadReadContext {
+    readonly walletClient: WalletClient;
+}
+/** Adapter boundary for generated ABI bindings and protocol-specific actions. */
+interface LaunchpadContractAdapter {
+    read<Result>(context: LaunchpadReadContext, request: LaunchpadReadRequest): Promise<Result>;
+    write<Result>(context: LaunchpadWriteContext, request: LaunchpadWriteRequest): Promise<Result>;
+}
+type LaunchpadAdapterRegistry = Readonly<Record<number, LaunchpadContractAdapter>>;
+interface LaunchpadClientConfig {
+    readonly publicClient: PublicClient;
+    readonly walletClient?: WalletClient;
+    readonly chains: LaunchpadChainRegistry;
+    readonly adapters?: LaunchpadAdapterRegistry;
+}
+interface LaunchpadClient {
+    readonly publicClient: PublicClient;
+    readonly walletClient?: WalletClient;
+    getChain(chainId?: number): LaunchpadChainConfig;
+    getAdapter(chainId?: number): LaunchpadContractAdapter;
+    read<Result>(request: LaunchpadReadRequest, chainId?: number): Promise<Result>;
+    write<Result>(request: LaunchpadWriteRequest, chainId?: number): Promise<Result>;
+}
+
+/** Allowance status for one asset/spender pair, resolved at a single block. */
+interface LaunchpadApprovalStatus {
+    readonly asset: Address;
+    readonly owner: Address;
+    readonly spender: Address;
+    readonly allowance: bigint;
+    readonly requiredAmount: bigint;
+    readonly sufficient: boolean;
+    /** Exactly the shortfall, so a caller can approve the precise amount still needed. */
+    readonly missingAmount: bigint;
+}
+/**
+ * Resolves whether an exact-amount approval is still required.
+ *
+ * The spender for both buy and sell is always the Portal — never a pool and never a future DEX
+ * router. For a buy, `requiredAmount` should be the quote's `quoteSpent` rather than the user's
+ * typed input, because a graduating buy spends less than requested.
+ */
+declare function getLaunchpadApprovalStatus(context: LaunchpadActionContext, input: {
+    readonly asset: Address;
+    readonly owner: Address;
+    readonly requiredAmount: bigint;
+    readonly spender?: Address;
+}, options?: LaunchpadReadOptions): Promise<LaunchpadApprovalStatus>;
+
+/**
+ * `ICurve.State` as the Portal builds it in `_curveState`. Every field is read from the deployed
+ * Portal's constants rather than hardcoded, so a redeployment with different curve parameters
+ * cannot silently produce wrong quotes.
+ */
+interface LaunchpadCurveState {
+    readonly totalSupply: bigint;
+    readonly circulatingSupply: bigint;
+    readonly quoteReserve: bigint;
+    readonly virtualTokenReserve: bigint;
+    readonly virtualQuoteReserve: bigint;
+    readonly k: bigint;
+}
+/** Portal curve constants, read once per deployment. */
+interface LaunchpadCurveConstants {
+    readonly totalSupply: bigint;
+    readonly dexSupplyThreshold: bigint;
+    readonly virtualTokenReserve: bigint;
+    readonly virtualQuoteReserve: bigint;
+    readonly curveK: bigint;
+}
+/**
+ * Builds the curve state the Portal would pass at token creation: nothing circulating and no
+ * quote reserve yet. Identical to `Portal._curveState()` for a freshly created token.
+ */
+declare function initialCurveState(constants: LaunchpadCurveConstants): LaunchpadCurveState;
+/**
+ * Fee applied to a creator's atomic first buy. `Portal._createToken` calls
+ * `_buy(..., creatorFirstBuy = true)`, which pins the fee to `TRADE_FEE_BPS` and bypasses the
+ * anti-sniper ladder entirely — the creator is never charged the launch-block rate.
+ */
+declare function creatorFirstBuyFee(quoteIn: bigint): bigint;
+/**
+ * Assembles a creator first-buy quote from the curve's own outputs.
+ *
+ * This mirrors `Portal._quoteBuy(state, quoteIn, creatorFirstBuy = true)` exactly. The two curve
+ * results must come from `eth_call`s against the deployed `ConstantProductCurve` — the SDK never
+ * reimplements the bonding-curve math in JavaScript. Only the flat fee and the `mulDivUp`
+ * gross-up run locally, and both are exact in `bigint`.
+ *
+ * @param quoteIn Total quote the creator commits, fee inclusive.
+ * @param tokenOutFromCurve `curve.quoteBuy(initialState, quoteIn - fee)`.
+ * @param netRequiredForThreshold `curve.quoteBuyExactOut(initialState, dexSupplyThreshold)`,
+ *   required only when the first buy alone would reach graduation.
+ */
+declare function toCreatorFirstBuyQuote(constants: LaunchpadCurveConstants, quoteIn: bigint, tokenOutFromCurve: bigint, netRequiredForThreshold?: bigint): BuyQuote;
+
+/**
+ * Scale factor baked into `Portal.priceWad`.
+ *
+ * The Portal computes `CURVE_K * 1e30 / effectiveBase²`, and `CURVE_K` is
+ * `VIRTUAL_QUOTE_RESERVE * (TOTAL_SUPPLY + VIRTUAL_TOKEN_RESERVE)` — a product of one amount in the
+ * quote's smallest unit and one in the token's. The quoted price is therefore
+ * `(quote smallest unit / token smallest unit) * 1e30`, independent of either token's decimals.
+ * Ratios against it need no decimals conversion, which is why nothing here takes one.
+ */
+declare const PRICE_WAD_SCALE: bigint;
+/**
+ * Price impact in basis points: how far the average execution price sits from the spot price.
+ *
+ * Positive means the trade executed worse than spot (a buy pushing up the curve), negative means
+ * better (a sell pushing down). Callers rendering a single figure usually want the magnitude.
+ *
+ * Both prices are expressed as quote-per-token, so the {@link PRICE_WAD_SCALE} cancels and no
+ * decimals are involved.
+ *
+ * @param spotPriceWad `Portal.priceWad` observed at the same block as the quote.
+ * @param quoteAmount Quote that actually moves along the curve, fee excluded.
+ * @param tokenAmount Token that moves in the same trade.
+ */
+declare function priceImpactBps(spotPriceWad: bigint, quoteAmount: bigint, tokenAmount: bigint): number;
+/**
+ * Price impact of a buy, with the protocol fee removed.
+ *
+ * `quoteSpent` is fee-inclusive but only `quoteSpent - fee` reaches the curve, so charging the fee
+ * to price impact would overstate it — the fee is a separate, flat cost a UI shows on its own line.
+ */
+declare function buyPriceImpactBps(spotPriceWad: bigint, quote: BuyQuote): number;
+/**
+ * Price impact of a sell, with the protocol fee added back.
+ *
+ * `quoteOut` is already net of the fee, so the gross amount the curve produced is `quoteOut + fee`.
+ * The result is negative: a sell moves the price down.
+ */
+declare function sellPriceImpactBps(spotPriceWad: bigint, quote: SellQuote, tokenIn: bigint): number;
+/**
+ * Converts `Portal.priceWad` into quote-per-whole-token, scaled to 1e18 for display.
+ *
+ * `priceWad` is a ratio of smallest units, so rendering it directly is only correct for one
+ * specific decimals pairing — with a 6-decimal quote and an 18-decimal token it happens to equal
+ * this result, which is why `formatUnits(priceWad, 18)` appears to work. Against an 18-decimal
+ * quote such as BNB or ETH that shortcut is off by twelve orders of magnitude, so the conversion
+ * is made explicit here rather than left to a coincidence.
+ */
+declare function priceWadPerWholeToken(priceWad: bigint, quoteDecimals: number, tokenDecimals?: number): bigint;
+/**
+ * Fully diluted market capitalisation, in the quote token's smallest unit.
+ *
+ * Uses `totalSupply` rather than circulating supply: the whole supply is minted at creation, with
+ * the un-sold remainder held by the Portal for the curve and the eventual V3 position.
+ */
+declare function marketCapQuote(priceWad: bigint, totalSupply: bigint): bigint;
+/**
+ * Reproduces `Portal._priceWad` for an arbitrary circulating supply.
+ *
+ * Lets a caller price a point the curve has not reached yet — the graduation price, or a series
+ * for a curve chart — without a round trip per point.
+ */
+declare function curvePriceWadAt(circulatingSupply: bigint, constants: LaunchpadCurveConstants): bigint;
+/**
+ * Market cap the token will have when it graduates, in the quote's smallest unit.
+ *
+ * This is the figure behind a "migrates at X" label. It is derived from the deployment's own curve
+ * constants rather than hard-coded, so it stays correct if a deployment is configured differently
+ * — and it is denominated in the quote token, not USD. Converting to USD needs an external price
+ * for the quote, which is the application's concern, not the SDK's.
+ */
+declare function graduationMarketCapQuote(constants: LaunchpadCurveConstants): bigint;
+/** Graduation progress of a bonding token, derived from supply rather than reserve. */
+interface LaunchpadGraduationProgress {
+    /** Token still purchasable on the curve before graduation, in the token's smallest unit. */
+    readonly tokensRemaining: bigint;
+    /** Progress toward the threshold, 0–10000. */
+    readonly progressBps: number;
+    /** True once the curve allocation is exhausted and the token is at or past graduation. */
+    readonly reachedThreshold: boolean;
+}
+/**
+ * Progress toward graduation, measured in supply.
+ *
+ * Supply is the condition the Portal actually tests (`tokenOut >= dexSupplyThreshold -
+ * circulatingSupply`), so this needs no hard-coded quote target and stays exact. A UI that
+ * displays "X / Y quote raised" can still show `quoteReserve` beside it, but the percentage
+ * belongs to supply.
+ *
+ * Already-graduated tokens report 100%: their reserve is moved into the V3 position at migration
+ * and reads back as zero, which would otherwise render as 0%.
+ */
+declare function graduationProgress(circulatingSupply: bigint, constants: LaunchpadCurveConstants): LaunchpadGraduationProgress;
+/** Fee a plain (non-creator) trade pays at the standard rate, in the quote's smallest unit. */
+declare function tradeFee(quoteAmount: bigint): bigint;
+
+/**
+ * Reads the Portal's curve constants.
+ *
+ * These are `immutable`/`constant` on a given Portal, so a caller may read them once per
+ * deployment and reuse the result. They are read from the contract rather than hardcoded so a
+ * redeployment with different curve parameters cannot silently produce wrong quotes.
+ */
+declare function getLaunchpadCurveConstants(context: LaunchpadActionContext, options?: LaunchpadReadOptions): Promise<LaunchpadCurveConstants>;
+/**
+ * Quotes the creator's atomic first buy, so `prepareCreateToken` can be given a non-zero
+ * `minInitialTokenOut` instead of the unsafe `0`.
+ *
+ * The Portal exposes no public creator-first-buy view: `_quoteBuy(..., creatorFirstBuy = true)` is
+ * internal, and simulating `createTokenV2` only returns the new token address. However the
+ * registered `ConstantProductCurve` is a deployed, stateless `pure` contract, so this reproduces
+ * the Portal's own arithmetic by calling that contract with the state a freshly created token
+ * would have. The bonding-curve math therefore runs as real Solidity, never as a JavaScript
+ * re-implementation; only the flat 1% fee and the `mulDivUp` gross-up happen locally, both exact
+ * in `bigint`.
+ *
+ * Pass `constants` to skip re-reading the Portal's immutable curve parameters on every quote.
+ */
+declare function quoteCreatorFirstBuy(context: LaunchpadActionContext, quoteIn: bigint, options?: LaunchpadReadOptions & {
+    readonly constants?: LaunchpadCurveConstants;
+}): Promise<BuyQuote>;
+/**
+ * Everything a token screen needs to render curve progress, resolved at one block.
+ *
+ * `apps/web` derived this from a hard-coded quote target and separate unpinned reads. Here the
+ * threshold comes from the deployment's own constants and every figure shares a block, so the
+ * headline market cap can never disagree with the progress bar beside it.
+ */
+interface LaunchpadCurveProgress extends LaunchpadGraduationProgress {
+    readonly blockNumber: bigint;
+    readonly phase: LaunchpadPhase;
+    readonly circulatingSupply: bigint;
+    /** Quote raised on the curve. Reads back as zero once migrated — the reserve moved into V3. */
+    readonly quoteReserve: bigint;
+    readonly priceWad: bigint;
+    /** Fully diluted market cap in the quote token's smallest unit. */
+    readonly marketCapQuote: bigint;
+    /**
+     * Market cap this token graduates at, in the quote's smallest unit.
+     *
+     * Derived from the deployment's curve constants, never hard-coded, and denominated in the quote
+     * token — a USD figure needs an external quote price, which the application owns.
+     */
+    readonly graduationMarketCapQuote: bigint;
+}
+/**
+ * Reads curve progress for one token: tokens remaining, percentage, and market cap.
+ *
+ * Constants are immutable per deployment, so a caller holding them may pass them in to save a
+ * round trip; otherwise they are read alongside everything else.
+ */
+declare function getLaunchpadCurveProgress(context: LaunchpadActionContext, token: Address, options?: LaunchpadReadOptions & {
+    readonly constants?: LaunchpadCurveConstants;
+}): Promise<LaunchpadCurveProgress>;
+
+/** Raised when a read is attempted with an input the Portal would reject outright. */
+declare class InvalidLaunchpadReadInputError extends Error {
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+/**
+ * Raised when a composite read that must observe one block is asked to use a tag with no stable
+ * height. `pending` names a block that does not exist yet, so nothing can be pinned to it.
+ */
+declare class UnpinnableBlockTagError extends Error {
+    readonly blockTag: string;
+    constructor(blockTag: string);
+}
+/**
+ * Resolves a concrete height that every part of a composite read can be pinned to.
+ *
+ * Reads that combine several calls must not each resolve `latest` independently: the chain head can
+ * advance between them, silently mixing one block's state with another block's height or pause
+ * flag. This collapses the caller's intent to a single number up front, so `latest`, `safe`,
+ * `finalized`, and an explicit height all carry the same "one observed block" guarantee.
+ *
+ * Exported so callers composing their own multi-read views get the same guarantee instead of
+ * resolving `latest` per call.
+ */
+declare function resolvePinnedBlockNumber(context: LaunchpadActionContext, options?: LaunchpadReadOptions): Promise<bigint>;
+/** Reads the Portal's token state and converts it to the stable domain shape. */
+declare function getLaunchpadTokenState(context: LaunchpadActionContext, token: Address, options?: LaunchpadReadOptions): Promise<LaunchpadTokenState>;
+/** Reads the raw, untrusted metadata string. Parsing is the caller's choice. */
+declare function getLaunchpadTokenMetadata(context: LaunchpadActionContext, token: Address, options?: LaunchpadReadOptions): Promise<string>;
+/**
+ * Reads the bonding-curve reference price, tagged with its source and the phase observed at the
+ * same block. This is never an executable quote and must not be used to derive a `minOut`; after
+ * graduation it remains a curve value and does not track the V3 pool.
+ *
+ * The price and the phase are pinned to one resolved height, so a `graduated` phase can never be
+ * reported alongside a price read from an earlier block (or the reverse).
+ */
+declare function getLaunchpadPrice(context: LaunchpadActionContext, token: Address, options?: LaunchpadReadOptions): Promise<LaunchpadPrice>;
+/** Quotes a curve buy. `quoteSpent` may be below `quoteIn` when the buy reaches graduation. */
+declare function quoteLaunchpadBuy(context: LaunchpadActionContext, token: Address, quoteIn: bigint, options?: LaunchpadReadOptions): Promise<BuyQuote>;
+/** Quotes a curve sell. `quoteOut` is already net of the trade fee. */
+declare function quoteLaunchpadSell(context: LaunchpadActionContext, token: Address, tokenIn: bigint, options?: LaunchpadReadOptions): Promise<SellQuote>;
+/**
+ * Combines token state, the global pause flag, and the block height into a single availability
+ * view, so a UI renders the fee, reason, and next tradable block without duplicating rules.
+ *
+ * The height is resolved **first**, then the state and pause flag are both pinned to it. Resolving
+ * them concurrently against `latest` would let the chain head advance mid-read and compute the
+ * protection-fee ladder for one block from another block's state — reporting the wrong fee and,
+ * inside the launch window, wrongly showing a banned token as tradable.
+ */
+declare function getLaunchpadTradeAvailability(context: LaunchpadActionContext, token: Address, options?: LaunchpadReadOptions): Promise<LaunchpadTradeAvailability>;
+/** Reads an ERC-20 balance at the given block. */
+declare function getErc20Balance(context: LaunchpadActionContext, asset: Address, account: Address, options?: LaunchpadReadOptions): Promise<bigint>;
+/**
+ * Reads a token's name, symbol, and decimals together at one block.
+ *
+ * The frontend integration guide lists these as required for any token screen, and reading them
+ * as one pinned batch keeps a header from pairing one token's symbol with another's decimals
+ * mid-render. Decimals matter most: formatting an amount with the wrong scale misstates it by
+ * orders of magnitude.
+ */
+declare function getErc20Metadata(context: LaunchpadActionContext, asset: Address, options?: LaunchpadReadOptions): Promise<LaunchpadErc20Metadata>;
+/** Reads an ERC-20 allowance at the given block. */
+declare function getErc20Allowance(context: LaunchpadActionContext, asset: Address, owner: Address, spender: Address, options?: LaunchpadReadOptions): Promise<bigint>;
+/**
+ * Reads a caller's claimable Locker reward for one asset. The Locker only ever exposes the
+ * caller's own balance, so `account` is a lookup key, not an authorization bypass.
+ */
+declare function getClaimableLaunchpadReward(context: LaunchpadActionContext, account: Address, asset: Address, options?: LaunchpadReadOptions): Promise<bigint>;
+/**
+ * Reads a locked V3 position by its LP NFT id, or `undefined` when nothing is registered.
+ *
+ * `tokenId` is the Uniswap V3 position NFT id minted during migration — not a token address. The
+ * Locker stores only `tokenId -> position`, with no reverse index, and this SDK does not scan logs
+ * to build one: `DATA_INDEXING_SPEC.md` assigns `PositionLocked`/`PositionMinted` to the indexing
+ * service and forbids browsers from scanning `eth_getLogs` from the deployment block. Callers
+ * therefore obtain `tokenId` from that service (or from the migration receipt) and pass it in.
+ */
+declare function getLockedLaunchpadPosition(context: LaunchpadActionContext, tokenId: bigint, options?: LaunchpadReadOptions): Promise<LaunchpadLockedPosition | undefined>;
+/**
+ * Predicts the CREATE2 address a token would receive if `creator` launched it right now.
+ *
+ * The Portal does not use `userSalt` directly — it derives the factory salt from the creator, an
+ * auto-incrementing per-creator nonce, and `userSalt`:
+ *
+ * ```solidity
+ * salt = keccak256(abi.encode(msg.sender, creatorNonces[msg.sender]++, params.userSalt));
+ * ```
+ *
+ * Reproducing that by hand is easy to get subtly wrong, so it lives here. The returned
+ * `creatorNonce` is part of the result rather than an internal detail: because the nonce increments
+ * on every successful creation, a prediction is only valid until this creator launches their next
+ * token. A UI offering to "reserve" an address must either create before that happens or re-check.
+ *
+ * This is a preview, not a reservation — nothing on-chain holds the address. Always take the real
+ * address from the `TokenCreated` event in the receipt.
+ */
+declare function predictLaunchpadTokenAddress(context: LaunchpadActionContext, input: {
+    readonly creator: Address;
+    readonly name: string;
+    readonly symbol: string;
+    readonly userSalt: Hex;
+}, options?: LaunchpadReadOptions): Promise<PredictedLaunchpadToken>;
+
+interface LaunchpadTokenCreatedEvent {
+    readonly token: Address;
+    readonly creator: Address;
+    readonly name: string;
+    readonly symbol: string;
+    readonly metadata: string;
+    readonly curveId: number;
+    readonly migratorId: number;
+}
+/**
+ * Direction-normalized trade event.
+ *
+ * The on-chain `quoteAmount` is asymmetric — the Portal emits the **net** quote on a buy and the
+ * **gross** quote on a sell — so the raw value alone cannot be summed into volume. `raw` is
+ * preserved for auditability while the derived deltas state, unambiguously, what the trader paid
+ * or received and how the curve reserve moved.
+ */
+interface LaunchpadTradeEvent {
+    readonly token: Address;
+    readonly trader: Address;
+    readonly side: "buy" | "sell";
+    readonly tokenAmount: bigint;
+    readonly quoteAmountRaw: bigint;
+    readonly fee: bigint;
+    /** Signed change in the trader's quote balance: buy is negative, sell positive. */
+    readonly traderQuoteDelta: bigint;
+    /** Signed change in the curve's quote reserve. */
+    readonly reserveQuoteDelta: bigint;
+}
+interface LaunchpadMigrationStartedEvent {
+    readonly token: Address;
+    readonly tokenAmount: bigint;
+    readonly quoteAmount: bigint;
+}
+interface LaunchpadMigrationCompletedEvent {
+    readonly token: Address;
+    readonly pool: Address;
+    readonly liquidity: bigint;
+    readonly lpRecipient: Address;
+}
+interface LaunchpadRewardsClaimedEvent {
+    readonly account: Address;
+    readonly asset: Address;
+    readonly recipient: Address;
+    readonly amount: bigint;
+}
+/** Everything the SDK could decode from one receipt, scoped to a single deployment. */
+interface LaunchpadReceiptEvents {
+    readonly tokenCreated: readonly LaunchpadTokenCreatedEvent[];
+    readonly trades: readonly LaunchpadTradeEvent[];
+    readonly migrationStarted: readonly LaunchpadMigrationStartedEvent[];
+    readonly migrationCompleted: readonly LaunchpadMigrationCompletedEvent[];
+    readonly rewardsClaimed: readonly LaunchpadRewardsClaimedEvent[];
+}
+/**
+ * Decodes the Launchpad events in a receipt.
+ *
+ * Logs are filtered by emitting address against the deployment, so a transaction that also touches
+ * unrelated contracts — or a look-alike contract emitting the same topic — cannot inject events
+ * that appear to come from this Portal.
+ */
+declare function parseLaunchpadReceiptEvents(deployment: LaunchpadDeployment, receipt: TransactionReceipt): LaunchpadReceiptEvents;
+/**
+ * Resolves the created token address from a receipt. The `TokenCreated` event is the only
+ * authority — `TokenFactory.predictAddress` is a preview, never a success signal.
+ */
+declare function createdTokenAddress(deployment: LaunchpadDeployment, receipt: TransactionReceipt): Address | undefined;
+
+/** Confirmed transaction plus the Launchpad events decoded from its receipt. */
+interface LaunchpadTransactionResult extends SdkTransactionResult {
+    readonly events: LaunchpadReceiptEvents;
+}
+/**
+ * Waits for a transaction and decodes its Launchpad events.
+ *
+ * A reverted receipt is reported as `status: "reverted"` rather than thrown, so a caller can tell
+ * "the chain rejected this" apart from "the request never landed". Events are still parsed, which
+ * is empty for a revert.
+ */
+declare function waitForLaunchpadTransaction(context: LaunchpadActionContext, hash: Hash, options?: {
+    readonly confirmations?: number;
+}): Promise<LaunchpadTransactionResult>;
+
+/**
+ * Compile-time brand. It exists only in the type system, so application code cannot construct a
+ * `PreparedLaunchpadTransaction` by writing an object literal — every value must come from one of
+ * this module's `prepare*` functions. Runtime provenance is enforced separately (see
+ * `assertPreparedProvenance` and the typed client's registry).
+ */
+declare const preparedLaunchpadTransactionBrand: unique symbol;
+/**
+ * The wallet and deployment context a prepared transaction was simulated under.
+ *
+ * Carried on the prepared value so the broadcast step can prove the wallet has not switched chain
+ * or account, and that the request belongs to the deployment now in use.
+ */
+interface PreparedLaunchpadTransactionContext {
+    readonly chainId: number;
+    readonly account: Address;
+    readonly portal: Address;
+}
+/**
+ * A simulated, ready-to-broadcast transaction plus the preview the simulation was based on.
+ * Holding these together stops a caller from submitting one intent while showing another.
+ */
+interface PreparedLaunchpadTransaction<Preview> {
+    readonly [preparedLaunchpadTransactionBrand]: true;
+    /** Frozen inspection copy; `send` uses a separate canonical snapshot retained by the SDK. */
+    readonly request: Readonly<Record<string, unknown>>;
+    readonly preview: Preview;
+    readonly context: PreparedLaunchpadTransactionContext;
+}
+interface CreateTokenPreview {
+    /** The full creator first-buy quote, or `undefined` when no first buy is made. */
+    readonly firstBuy?: BuyQuote;
+    readonly initialQuoteIn: bigint;
+    readonly minInitialTokenOut: bigint;
+    readonly protectionBlocks: number;
+    readonly deadline: bigint;
+}
+interface MigrationPreview {
+    readonly token: Address;
+}
+interface ClaimPreview {
+    readonly asset: Address;
+    readonly recipient: Address;
+    readonly amount: bigint;
+}
+/**
+ * Outcome of collecting a locked V3 position's fees, simulated before broadcast.
+ *
+ * `amount0`/`amount1` are the gross amounts the Locker pulls from the position manager; the
+ * creator's share is what lands in `pendingRewards` after `platformFeeBps` is taken.
+ */
+interface CollectFeesPreview {
+    readonly tokenId: bigint;
+    readonly token0: Address;
+    readonly token1: Address;
+    readonly creator: Address;
+    readonly platformFeeBps: number;
+    readonly amount0: bigint;
+    readonly amount1: bigint;
+}
+interface ApprovalPreview {
+    readonly asset: Address;
+    readonly spender: Address;
+    readonly amount: bigint;
+}
+/**
+ * Prepares an ERC-20 approval for an exact amount.
+ *
+ * The SDK never widens this to an unlimited allowance on the caller's behalf; a UI wanting
+ * `maxUint256` must pass it explicitly and show its own risk confirmation.
+ */
+declare function prepareApproveErc20(context: LaunchpadWriteActionContext, input: {
+    readonly asset: Address;
+    readonly amount: bigint;
+    readonly spender?: Address;
+}): Promise<PreparedLaunchpadTransaction<ApprovalPreview>>;
+/**
+ * Prepares a bonding-curve buy: refreshes the quote, derives a non-zero `minTokenOut` from the
+ * caller's slippage, verifies the allowance covers `quoteSpent`, then simulates.
+ */
+declare function prepareLaunchpadBuy(context: LaunchpadWriteActionContext, input: {
+    readonly token: Address;
+    readonly quoteIn: bigint;
+    readonly slippage: Slippage;
+    readonly deadline: bigint;
+}): Promise<PreparedLaunchpadTransaction<BuyQuote>>;
+/** Prepares a bonding-curve sell with a non-zero `minQuoteOut` and a Portal-scoped allowance. */
+declare function prepareLaunchpadSell(context: LaunchpadWriteActionContext, input: {
+    readonly token: Address;
+    readonly tokenIn: bigint;
+    readonly slippage: Slippage;
+    readonly deadline: bigint;
+}): Promise<PreparedLaunchpadTransaction<SellQuote>>;
+/** Input for {@link prepareCreateToken}. */
+interface CreateTokenInput {
+    readonly name: string;
+    readonly symbol: string;
+    readonly metadata: string;
+    readonly userSalt: Hex;
+    /** Quote committed to the creator's atomic first buy. Zero means no first buy. */
+    readonly initialQuoteIn: bigint;
+    readonly deadline: bigint;
+    readonly protectionBlocks: number;
+    /**
+     * Slippage tolerance used to derive `minInitialTokenOut` from the creator first-buy quote.
+     * Required when `initialQuoteIn > 0`, unless `minInitialTokenOut` is supplied instead.
+     */
+    readonly slippage?: Slippage;
+    /**
+     * Advanced escape hatch: an explicit minimum that overrides the slippage-derived value.
+     *
+     * Kept only for callers who compute the minimum themselves against their own quote. It must be
+     * positive whenever a first buy is made and must not exceed the SDK's own fresh quote (which
+     * would revert on-chain). It is never a way to opt out of slippage protection: passing `0` with
+     * a first buy is rejected, so there is no unsafe default path.
+     */
+    readonly minInitialTokenOut?: bigint;
+}
+/**
+ * Prepares token creation, deriving a safe non-zero `minInitialTokenOut` for the creator's atomic
+ * first buy.
+ *
+ * When `initialQuoteIn > 0` the SDK prices the first buy itself via the deployed curve
+ * ({@link quoteCreatorFirstBuy}) and applies the caller's slippage, so a caller never has to invent
+ * a minimum. Two contract details drive the rest:
+ *
+ * - The allowance is checked against `quote.quoteSpent`, not `initialQuoteIn`. A first buy large
+ *   enough to graduate is truncated at the threshold and the Portal transfers only `quoteSpent`, so
+ *   requiring the full input would demand an allowance the transaction never uses.
+ * - The simulation still passes the caller's raw `initialQuoteIn`, because the Portal performs that
+ *   truncation itself; passing `quoteSpent` would change the intent.
+ *
+ * When `initialQuoteIn` is zero, `minInitialTokenOut` must also be zero — the Portal rejects any
+ * other combination.
+ */
+declare function prepareCreateToken(context: LaunchpadWriteActionContext, input: CreateTokenInput): Promise<PreparedLaunchpadTransaction<CreateTokenPreview>>;
+/** Prepares the permissionless migration. Only valid while the token is `migrating`. */
+declare function prepareLaunchpadMigration(context: LaunchpadWriteActionContext, token: Address): Promise<PreparedLaunchpadTransaction<MigrationPreview>>;
+/**
+ * Prepares a fee collection for a locked V3 position.
+ *
+ * This is the step that funds a claim: it pulls the position's accrued V3 fees into the Locker and
+ * credits the creator's share to `pendingRewards`. Until it runs there is nothing to claim, so a
+ * rewards UI that only exposes `prepareClaimReward` can never pay anyone out.
+ *
+ * Permissionless by design — the Locker credits `positions[tokenId].creator`, never the caller, so
+ * anyone may trigger collection and it is deliberately *not* behind the `rewards` capability.
+ * Gating it would let a disabled capability strand fees that belong to creators.
+ *
+ * `tokenId` is the Uniswap V3 position NFT id, obtained from the indexing service or the migration
+ * receipt; see {@link getLockedLaunchpadPosition} for why the SDK cannot resolve it from a token
+ * address.
+ */
+declare function prepareCollectLaunchpadFees(context: LaunchpadWriteActionContext, tokenId: bigint): Promise<PreparedLaunchpadTransaction<CollectFeesPreview>>;
+/**
+ * Prepares a Locker reward claim.
+ *
+ * The Locker only ever pays out `pendingRewards[msg.sender]`, so a claim can never drain another
+ * account. Callers must gate this behind the deployment's `rewards` capability, which is off by
+ * default until the product confirms the claim surface.
+ *
+ * A claim only pays out what {@link prepareCollectLaunchpadFees} has already credited.
+ */
+declare function prepareClaimLaunchpadReward(context: LaunchpadWriteActionContext, input: {
+    readonly asset: Address;
+    readonly recipient?: Address;
+}): Promise<PreparedLaunchpadTransaction<ClaimPreview>>;
+/**
+ * Broadcasts an already-simulated transaction. Never simulates or mutates the request here.
+ *
+ * The module-private canonical-request registry also protects this standalone action: structural
+ * copies and hand-built values have no canonical simulation request and are rejected.
+ */
+declare function sendPreparedLaunchpadTransaction(context: LaunchpadWriteActionContext, prepared: PreparedLaunchpadTransaction<unknown>): Promise<Hash>;
+
+declare class InvalidLaunchpadChainConfigError extends Error {
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+/** Validates, normalizes, and freezes a caller-supplied chain configuration. */
+declare function defineLaunchpadChain(input: LaunchpadChainConfig): Readonly<LaunchpadChainConfig>;
+/** Normalizes an EVM token address while preserving its chain-scoped identity. */
+declare function defineLaunchpadTokenId(input: LaunchpadTokenId): Readonly<LaunchpadTokenId>;
+
+/** Creates a chain-scoped, ABI-neutral Launchpad client around caller-provided adapters. */
+declare function createLaunchpadClient(config: LaunchpadClientConfig): LaunchpadClient;
+declare class UnsupportedLaunchpadCapabilityError extends Error {
+    readonly chainId: number;
+    readonly capability: LaunchpadWriteRequest["requiredCapability"];
+    constructor(chainId: number, capability: LaunchpadWriteRequest["requiredCapability"]);
+}
+
+/** Raw `Portal.getTokenState` tuple. Consumers must never index this positionally. */
+interface RawLaunchpadTokenState {
+    readonly status: number;
+    readonly tokenVersion: number;
+    readonly curveId: number;
+    readonly migratorId: number;
+    readonly quoteReserve: bigint;
+    readonly circulatingSupply: bigint;
+    readonly creator: Address;
+    readonly dexPool: Address;
+    readonly launchBlock: bigint;
+    readonly protectionBlocks: number;
+    readonly pauseMode: number;
+}
+declare class InvalidLaunchpadStateError extends Error {
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+/** Maps `Portal.Status` to a stable phase name. */
+declare function toLaunchpadPhase(status: number): LaunchpadPhase;
+/** Maps `Portal.TokenState.pauseMode` to a stable pause name. */
+declare function toLaunchpadPauseMode(pauseMode: number): LaunchpadPauseMode;
+/**
+ * Converts the raw Portal state tuple into the stable domain shape.
+ *
+ * `dexPool` is omitted rather than reported as the zero address, so a caller can never mistake an
+ * unprepared pool for a tradable one. The pool is only meaningful once the token has graduated;
+ * it is populated at creation time for the migrator, so it is suppressed while `invalid`.
+ */
+declare function toLaunchpadTokenState(id: LaunchpadTokenId, raw: RawLaunchpadTokenState): LaunchpadTokenState;
+
+/** Arc Testnet chain id. Testnet-only; never treated as a production default. */
+declare const arcTestnetChainId = 5042002;
+/**
+ * Explicitly named Arc Testnet V2 development deployment (deployed 2026-08-13).
+ *
+ * This is a development configuration, not a production default: it is deliberately excluded from
+ * `launchpadDeploymentRegistry`, and consumers must opt in by name. Addresses, the Portal runtime
+ * code hash, and the deployment block were read from Arc Testnet and cross-checked against the
+ * contract repository's deployment record at the pinned revision. Callers should still run
+ * `verifyLaunchpadDeployment` before trusting it.
+ */
+declare const arcTestnetLaunchpadDeployment: Readonly<LaunchpadDeployment>;
+
+/** Base class for every stable Launchpad failure, so callers can branch on one instanceof. */
+declare class LaunchpadError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The token is not in a phase that permits the attempted operation. */
+declare class LaunchpadPhaseUnavailableError extends LaunchpadError {
+    readonly phase?: LaunchpadPhase;
+    constructor(phase?: LaunchpadPhase, options?: {
+        cause?: unknown;
+    });
+}
+/** Trading is paused, either protocol-wide or for this token. */
+declare class LaunchpadTradingPausedError extends LaunchpadError {
+    readonly scope: "protocol" | "token";
+    readonly mode?: LaunchpadPauseMode;
+    constructor(scope: "protocol" | "token", mode?: LaunchpadPauseMode, options?: {
+        cause?: unknown;
+    });
+}
+/** The launch block forbids trading; retry from `nextEligibleBlock`. */
+declare class LaunchpadProtectionError extends LaunchpadError {
+    readonly nextEligibleBlock?: bigint;
+    constructor(nextEligibleBlock?: bigint, options?: {
+        cause?: unknown;
+    });
+}
+/** The quote moved past the caller's tolerance; re-quote before retrying. */
+declare class LaunchpadSlippageError extends LaunchpadError {
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
+/** The deadline elapsed. The transaction must be rebuilt, never replayed. */
+declare class LaunchpadDeadlineExpiredError extends LaunchpadError {
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
+/** An ERC-20 approval is required before the operation can succeed. */
+declare class LaunchpadApprovalRequiredError extends LaunchpadError {
+    readonly asset: Address;
+    readonly spender: Address;
+    readonly requiredAmount: bigint;
+    constructor(asset: Address, spender: Address, requiredAmount: bigint);
+}
+/**
+ * The account cannot cover the amount a transfer would move.
+ *
+ * Checked alongside the allowance during `prepare*`, because the Portal moves funds through
+ * `SafeTransferLib`, which collapses every underlying failure into an opaque `TransferFailed()`.
+ * Without this check an insufficient balance surfaces as an unmapped revert that gives the caller
+ * no way to tell "top up" apart from a genuine contract fault.
+ */
+declare class LaunchpadInsufficientBalanceError extends LaunchpadError {
+    readonly asset: Address;
+    readonly account: Address;
+    readonly requiredAmount: bigint;
+    readonly balance: bigint;
+    constructor(asset: Address, account: Address, requiredAmount: bigint, balance: bigint);
+}
+/**
+ * The wallet switched accounts between preparing and broadcasting.
+ *
+ * The simulated request is bound to the account it was prepared for — allowances, balances, and the
+ * `from` address were all resolved against it — so it must not be sent from a different account.
+ */
+declare class PreparedAccountMismatchError extends LaunchpadError {
+    readonly expectedAccount: Address;
+    readonly actualAccount: Address;
+    constructor(expectedAccount: Address, actualAccount: Address);
+}
+/**
+ * The value passed to a send call did not originate from this SDK's prepare pipeline, or belongs to
+ * a different deployment. Broadcasting it would skip simulation and the safety checks around it.
+ */
+declare class ForgedPreparedTransactionError extends LaunchpadError {
+    constructor(message: string);
+}
+/** A write was attempted on a client constructed without a Wallet Client. */
+declare class MissingWalletClientError extends LaunchpadError {
+    constructor();
+}
+/** There is no claimable balance for this account and asset; the Locker would revert. */
+declare class LaunchpadNothingToClaimError extends LaunchpadError {
+    readonly asset: Address;
+    readonly account: Address;
+    constructor(asset: Address, account: Address);
+}
+/**
+ * No locked position is registered under the given LP NFT id.
+ *
+ * Usually means the id came from the wrong source: it is a Uniswap V3 position NFT id, not a token
+ * address, and only ids minted by this deployment's migrator are registered here.
+ */
+declare class LaunchpadUnknownPositionError extends LaunchpadError {
+    readonly tokenId: bigint;
+    constructor(tokenId: bigint);
+}
+/**
+ * The official V3 pool rejects liquidity operations before graduation.
+ *
+ * `LaunchToken` keeps its official pool locked until the Portal migrates it, so an attempt to seed
+ * or trade that pool early reverts here rather than silently competing with the bonding curve.
+ */
+declare class LaunchpadOfficialPoolLockedError extends LaunchpadError {
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
+/** The wallet is connected to a different chain than the requested deployment. */
+declare class WrongWalletChainError extends LaunchpadError {
+    readonly expectedChainId: number;
+    readonly actualChainId?: number;
+    constructor(expectedChainId: number, actualChainId?: number);
+}
+/** Extracts the reverted custom-error name from a viem error chain, if present. */
+declare function revertErrorName(error: unknown): string | undefined;
+/**
+ * Maps a contract failure onto a stable SDK error using the decoded custom-error name, never the
+ * message text. Unrecognized failures fall back to the shared core error codes, preserving the
+ * original cause and request metadata.
+ */
+declare function toLaunchpadError(error: unknown): Error;
+
+/** Regular curve trade fee once the protection window has elapsed (`Portal.TRADE_FEE_BPS`). */
+declare const TRADE_FEE_BPS = 100;
+/** `Portal.BPS`. A fee of exactly this value means trading is disabled, not a 100% fee. */
+declare const BPS = 10000;
+/** `Portal.MAX_PROTECTION_BLOCKS`. Creators may choose fewer, so never assume this value. */
+declare const MAX_PROTECTION_BLOCKS = 6;
+/**
+ * Reproduces `Portal._tradeFeeBps(state)` for a given block.
+ *
+ * Returns `BPS` (10000) only for the launch block itself, which the Portal rejects with
+ * `LaunchBlockTradingDisabled`. Use {@link isLaunchBlockTradingDisabled} rather than comparing
+ * the returned fee to 10000 at call sites.
+ */
+declare function tradeFeeBpsAt(launchBlock: bigint, protectionBlocks: number, blockNumber: bigint): number;
+/** True when the Portal would revert with `LaunchBlockTradingDisabled` at this block. */
+declare function isLaunchBlockTradingDisabled(launchBlock: bigint, protectionBlocks: number, blockNumber: bigint): boolean;
+/**
+ * First block at which curve trading is permitted. With `protectionBlocks === 0` the ladder is
+ * skipped entirely and the launch block itself is tradable.
+ */
+declare function firstTradableBlock(launchBlock: bigint, protectionBlocks: number): bigint;
+/**
+ * Derives trade availability from already-read state, so a UI can render the fee, the reason
+ * trading is blocked, and the next tradable block without duplicating protection rules.
+ */
+declare function toLaunchpadTradeAvailability(state: LaunchpadTokenState, blockNumber: bigint, protocolPaused: boolean): LaunchpadTradeAvailability;
+
+/** Hard ceiling on caller-supplied slippage. Anything above this is rejected outright. */
+declare const MAX_SLIPPAGE_BPS = 1000;
+/** Default deadline horizon: ten minutes from the reference chain time. */
+declare const DEFAULT_DEADLINE_SECONDS = 600n;
+declare class InvalidSlippageError extends Error {
+    readonly bps: number;
+    constructor(bps: number, message: string);
+}
+declare class InvalidDeadlineError extends Error {
+    constructor(message: string);
+}
+/** Validates a slippage tolerance against the 0..10% range. */
+declare function assertSlippage(slippage: Slippage): number;
+/**
+ * Applies slippage to a quoted output, rounding **down** so the on-chain minimum is never more
+ * optimistic than the quote. Rejects a zero expected output, because a zero `minOut` would
+ * disable the contract's own slippage guard.
+ */
+declare function applySlippageToMinimumOut(expectedOut: bigint, slippage: Slippage): bigint;
+/**
+ * Builds a transaction deadline from a reference chain timestamp. The reference must come from a
+ * block, not the client clock, because the Portal compares against `block.timestamp`.
+ */
+declare function toDeadline(referenceTimestamp: bigint, seconds?: bigint): bigint;
+/** Rounds up `x * y / denominator`, mirroring `Portal._mulDivUp`. */
+declare function mulDivUp(x: bigint, y: bigint, denominator: bigint): bigint;
+
+/**
+ * Parsed view of `CreateParams.metadata`. Every field is optional because the on-chain value is an
+ * opaque, untrusted string that any creator can set to anything.
+ *
+ * The SDK deliberately does not validate URL schemes, fetch images, sanitize HTML, or moderate
+ * content — that belongs to the application and its metadata service. `raw` is always preserved so
+ * callers can apply their own policy.
+ */
+interface LaunchpadMetadata {
+    readonly raw: string;
+    /** True only when `raw` parsed as a JSON object. */
+    readonly valid: boolean;
+    readonly description?: string;
+    readonly image?: string;
+    readonly website?: string;
+    /** Any other top-level keys, preserved without interpretation. */
+    readonly extra: Readonly<Record<string, unknown>>;
+}
+/**
+ * Parses token metadata without ever throwing. Invalid JSON, JSON primitives, arrays, `null`, and
+ * unexpected field types all degrade to `valid: false` (or a missing field) rather than an error,
+ * so a single malformed token can never break a list render.
+ */
+declare function parseLaunchpadMetadata(raw: string): LaunchpadMetadata;
+
+/**
+ * Typed client configuration.
+ *
+ * The client is configured from a single {@link LaunchpadChainConfig}, which already carries the
+ * verified {@link LaunchpadDeployment} plus the product `capabilities`. Taking one object avoids the
+ * drift that two parallel sources (a deployment here, capabilities elsewhere) would allow, and it
+ * makes the capability gate impossible to omit.
+ */
+interface LaunchpadPortalClientConfig {
+    readonly publicClient: PublicClient;
+    readonly walletClient?: WalletClient;
+    readonly chain: LaunchpadChainConfig;
+}
+/**
+ * Strongly typed client bound to one verified deployment.
+ *
+ * This is the primary business API. The ABI-neutral `adapter.read/write` client remains available
+ * for versions this SDK does not yet cover and for test adapters, but production call sites should
+ * use these methods.
+ *
+ * Write paths are gated by the chain's declared capabilities, so a product that has not enabled
+ * rewards (the default) cannot prepare a claim even by mistake. Reads are never gated: a page must
+ * be able to render state without a signer and regardless of which writes are enabled.
+ */
+interface LaunchpadPortalClient {
+    readonly chain: LaunchpadChainConfig;
+    readonly deployment: LaunchpadDeployment;
+    readonly publicClient: PublicClient;
+    readonly walletClient?: WalletClient;
+    getTokenState(token: Address, options?: LaunchpadReadOptions): Promise<LaunchpadTokenState>;
+    getTokenMetadata(token: Address, options?: LaunchpadReadOptions): Promise<string>;
+    getPrice(token: Address, options?: LaunchpadReadOptions): Promise<LaunchpadPrice>;
+    quoteBuy(token: Address, quoteIn: bigint, options?: LaunchpadReadOptions): Promise<BuyQuote>;
+    quoteSell(token: Address, tokenIn: bigint, options?: LaunchpadReadOptions): Promise<SellQuote>;
+    /** Curve constants for this deployment; immutable, so callers may cache the result. */
+    getCurveConstants(options?: LaunchpadReadOptions): Promise<LaunchpadCurveConstants>;
+    /**
+     * Prices a creator's atomic first buy. `prepareCreateToken` calls this internally, so a caller
+     * only needs it to preview a first buy before committing to one.
+     */
+    quoteCreatorFirstBuy(quoteIn: bigint, options?: LaunchpadReadOptions & {
+        readonly constants?: LaunchpadCurveConstants;
+    }): Promise<BuyQuote>;
+    getTradeAvailability(token: Address, options?: LaunchpadReadOptions): Promise<LaunchpadTradeAvailability>;
+    getBalance(asset: Address, account: Address, options?: LaunchpadReadOptions): Promise<bigint>;
+    getAllowance(asset: Address, owner: Address, spender: Address, options?: LaunchpadReadOptions): Promise<bigint>;
+    getApprovalStatus(input: {
+        readonly asset: Address;
+        readonly owner: Address;
+        readonly requiredAmount: bigint;
+        readonly spender?: Address;
+    }, options?: LaunchpadReadOptions): Promise<LaunchpadApprovalStatus>;
+    getClaimableReward(account: Address, asset: Address, options?: LaunchpadReadOptions): Promise<bigint>;
+    /** Token name, symbol, and decimals, read together at one block. */
+    getErc20Metadata(asset: Address, options?: LaunchpadReadOptions): Promise<LaunchpadErc20Metadata>;
+    /**
+     * Looks up a locked V3 position by its LP NFT id, or `undefined` when unregistered.
+     *
+     * The id comes from the indexing service or a migration receipt — the Locker keeps no reverse
+     * index from token address to `tokenId`.
+     */
+    getLockedPosition(tokenId: bigint, options?: LaunchpadReadOptions): Promise<LaunchpadLockedPosition | undefined>;
+    /**
+     * Curve progress for a token screen: tokens remaining, percentage, and market cap, all pinned to
+     * one block. Pass `constants` to reuse an already-read copy.
+     */
+    getCurveProgress(token: Address, options?: LaunchpadReadOptions & {
+        readonly constants?: LaunchpadCurveConstants;
+    }): Promise<LaunchpadCurveProgress>;
+    /**
+     * Previews the CREATE2 address a token would get if this creator launched it now.
+     *
+     * A preview, not a reservation: the Portal mixes an auto-incrementing per-creator nonce into the
+     * salt, so the prediction stops holding once this creator launches anything. Take the real
+     * address from the receipt's `TokenCreated` event.
+     */
+    predictTokenAddress(input: {
+        readonly creator: Address;
+        readonly name: string;
+        readonly symbol: string;
+        readonly userSalt: Hex;
+    }, options?: LaunchpadReadOptions): Promise<PredictedLaunchpadToken>;
+    /** ERC-20 approval. Ungated: a plain token approval is not a Launchpad protocol write. */
+    prepareApprove(input: {
+        readonly asset: Address;
+        readonly amount: bigint;
+        readonly spender?: Address;
+    }): Promise<PreparedLaunchpadTransaction<ApprovalPreview>>;
+    /** Requires the `create` capability. */
+    prepareCreateToken(input: CreateTokenInput): Promise<PreparedLaunchpadTransaction<CreateTokenPreview>>;
+    /** Requires the `bondingTrade` capability. */
+    prepareBuy(input: {
+        readonly token: Address;
+        readonly quoteIn: bigint;
+        readonly slippage: Slippage;
+        readonly deadline: bigint;
+    }): Promise<PreparedLaunchpadTransaction<BuyQuote>>;
+    /** Requires the `bondingTrade` capability. */
+    prepareSell(input: {
+        readonly token: Address;
+        readonly tokenIn: bigint;
+        readonly slippage: Slippage;
+        readonly deadline: bigint;
+    }): Promise<PreparedLaunchpadTransaction<SellQuote>>;
+    /**
+     * Migration is permissionless on-chain and completes a token that has already graduated, so it is
+     * deliberately **not** gated by a product capability — disabling it would leave graduated tokens
+     * stranded even though anyone can call `migrate`.
+     */
+    prepareMigration(token: Address): Promise<PreparedLaunchpadTransaction<MigrationPreview>>;
+    /**
+     * Collects a locked position's V3 fees into the Locker, crediting the creator's share.
+     *
+     * Permissionless like migration, and likewise **not** gated by `rewards`: the Locker always
+     * credits `positions[tokenId].creator` rather than the caller, and gating it would strand fees
+     * that belong to creators whenever the capability is off. It is the step that makes
+     * `prepareClaimReward` able to pay out anything at all.
+     */
+    prepareCollectFees(tokenId: bigint): Promise<PreparedLaunchpadTransaction<CollectFeesPreview>>;
+    /** Requires the `rewards` capability, which defaults to off. */
+    prepareClaimReward(input: {
+        readonly asset: Address;
+        readonly recipient?: Address;
+    }): Promise<PreparedLaunchpadTransaction<ClaimPreview>>;
+    send(prepared: PreparedLaunchpadTransaction<unknown>): Promise<Hash>;
+    wait(hash: Hash, options?: {
+        readonly confirmations?: number;
+    }): Promise<LaunchpadTransactionResult>;
+}
+/** Creates a typed client for one verified Launchpad deployment. */
+declare function createLaunchpadPortalClient(config: LaunchpadPortalClientConfig): LaunchpadPortalClient;
+
+/** Raised when on-chain state contradicts a registered deployment. */
+declare class LaunchpadDeploymentVerificationError extends Error {
+    readonly field: string;
+    readonly expected: string;
+    readonly actual: string;
+    constructor(field: string, expected: string, actual: string);
+}
+/**
+ * Verifies that a registered {@link LaunchpadDeployment} matches live chain state before it is
+ * trusted: the connected chain id, the Portal runtime bytecode hash, the Portal's core bindings
+ * and default module registrations, and the Migrator/Locker cross-bindings. Throws
+ * {@link LaunchpadDeploymentVerificationError} on the first mismatch. This performs read-only
+ * calls; it never writes or broadcasts.
+ */
+declare function verifyLaunchpadDeployment(publicClient: PublicClient, deployment: LaunchpadDeployment): Promise<void>;
+
+export { type ApprovalPreview, BPS, type BuyQuote, type ClaimPreview, type CollectFeesPreview, type CreateTokenInput, type CreateTokenPreview, DEFAULT_DEADLINE_SECONDS, ForgedPreparedTransactionError, InvalidDeadlineError, InvalidLaunchpadChainConfigError, InvalidLaunchpadDeploymentError, InvalidLaunchpadReadInputError, InvalidLaunchpadStateError, InvalidSlippageError, type LaunchpadActionContext, type LaunchpadAdapterRegistry, LaunchpadApprovalRequiredError, type LaunchpadApprovalStatus, type LaunchpadAssetRef, type LaunchpadCapability, type LaunchpadChainConfig, type LaunchpadChainRegistry, type LaunchpadClient, type LaunchpadClientConfig, type LaunchpadContractAdapter, type LaunchpadContracts, type LaunchpadCurveConstants, type LaunchpadCurveProgress, type LaunchpadCurveState, LaunchpadDeadlineExpiredError, type LaunchpadDeployment, type LaunchpadDeploymentRegistry, LaunchpadDeploymentVerificationError, type LaunchpadErc20Metadata, LaunchpadError, type LaunchpadGraduationProgress, LaunchpadInsufficientBalanceError, type LaunchpadLockedPosition, type LaunchpadMetadata, type LaunchpadMigrationCompletedEvent, type LaunchpadMigrationStartedEvent, LaunchpadNothingToClaimError, LaunchpadOfficialPoolLockedError, type LaunchpadPauseMode, type LaunchpadPhase, LaunchpadPhaseUnavailableError, type LaunchpadPortalClient, type LaunchpadPortalClientConfig, type LaunchpadPrice, LaunchpadProtectionError, type LaunchpadQuoteTokenConfig, type LaunchpadReadContext, type LaunchpadReadOptions, type LaunchpadReadRequest, type LaunchpadReceiptEvents, type LaunchpadRewardsClaimedEvent, LaunchpadSlippageError, type LaunchpadTokenCreatedEvent, type LaunchpadTokenId, type LaunchpadTokenState, type LaunchpadTradeAvailability, type LaunchpadTradeBlockedReason, type LaunchpadTradeEvent, LaunchpadTradingPausedError, type LaunchpadTransactionResult, LaunchpadUnknownPositionError, type LaunchpadWriteActionContext, type LaunchpadWriteContext, type LaunchpadWriteRequest, MAX_PROTECTION_BLOCKS, MAX_SLIPPAGE_BPS, type MigrationPreview, MissingWalletClientError, PRICE_WAD_SCALE, type PredictedLaunchpadToken, PreparedAccountMismatchError, type PreparedLaunchpadTransaction, type PreparedLaunchpadTransactionContext, type RawLaunchpadTokenState, type SellQuote, type Slippage, TRADE_FEE_BPS, UnpinnableBlockTagError, UnsupportedLaunchpadCapabilityError, WrongWalletChainError, applySlippageToMinimumOut, arcTestnetChainId, arcTestnetLaunchpadDeployment, assertSlippage, buyPriceImpactBps, createLaunchpadClient, createLaunchpadPortalClient, createdTokenAddress, creatorFirstBuyFee, curvePriceWadAt, defineLaunchpadChain, defineLaunchpadDeployment, defineLaunchpadDeploymentRegistry, defineLaunchpadTokenId, firstTradableBlock, getClaimableLaunchpadReward, getErc20Allowance, getErc20Balance, getErc20Metadata, getLaunchpadApprovalStatus, getLaunchpadCurveConstants, getLaunchpadCurveProgress, getLaunchpadPrice, getLaunchpadTokenMetadata, getLaunchpadTokenState, getLaunchpadTradeAvailability, getLockedLaunchpadPosition, graduationMarketCapQuote, graduationProgress, initialCurveState, isLaunchBlockTradingDisabled, launchpadDeploymentRegistry, marketCapQuote, mulDivUp, parseLaunchpadMetadata, parseLaunchpadReceiptEvents, predictLaunchpadTokenAddress, prepareApproveErc20, prepareClaimLaunchpadReward, prepareCollectLaunchpadFees, prepareCreateToken, prepareLaunchpadBuy, prepareLaunchpadMigration, prepareLaunchpadSell, priceImpactBps, priceWadPerWholeToken, quoteCreatorFirstBuy, quoteLaunchpadBuy, quoteLaunchpadSell, resolveLaunchpadDeployment, resolvePinnedBlockNumber, revertErrorName, sellPriceImpactBps, sendPreparedLaunchpadTransaction, toCreatorFirstBuyQuote, toDeadline, toLaunchpadError, toLaunchpadPauseMode, toLaunchpadPhase, toLaunchpadTokenState, toLaunchpadTradeAvailability, tradeFee, tradeFeeBpsAt, verifyLaunchpadDeployment, waitForLaunchpadTransaction };