@latchprotocol/widgets 0.1.0

package/dist/core/clMath.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Concentrated-liquidity arithmetic, transcribed from the pool's own formulas.
+ *
+ * The live adapter uses this to turn desired amounts into a liquidity figure
+ * (`quoteAddLiquidity`), a position's liquidity back into the amounts a
+ * withdrawal returns (`quoteRemoveLiquidity`, `listPositions`) and its
+ * uncollected fees. Nothing here estimates: a wrong constant would render a
+ * number that LOOKS real and is not, so the constants are copied verbatim from
+ * `TickMath.sol` and {@link assertTickMathSelfConsistent} checks the
+ * transcription against values the chain publishes.
+ *
+ * Rounding directions match the contracts: an add rounds **up** (the pool takes
+ * one wei more), a remove rounds **down** (it returns one wei less).
+ *
+ * - `TickMath.getSqrtRatioAtTick`
+ * - `SqrtPriceMath.getAmount{0,1}Delta`
+ * - `LiquidityAmounts.getLiquidityForAmounts`
+ * - `Tick.getFeeGrowthInside` + `CLPosition.update` (fees owed)
+ */
+/** 2^96. */
+export declare const Q96: bigint;
+/** Lowest tick a pool can quote. */
+export declare const MIN_TICK = -887272;
+/** Highest tick a pool can quote. */
+export declare const MAX_TICK = 887272;
+/** `TickMath.getSqrtRatioAtTick`. */
+export declare function getSqrtRatioAtTick(tick: number): bigint;
+/** `SqrtPriceMath.getAmount0Delta`. */
+export declare function getAmount0Delta(sqrtRatioAX96: bigint, sqrtRatioBX96: bigint, liquidity: bigint, roundUp: boolean): bigint;
+/** `SqrtPriceMath.getAmount1Delta`. */
+export declare function getAmount1Delta(sqrtRatioAX96: bigint, sqrtRatioBX96: bigint, liquidity: bigint, roundUp: boolean): bigint;
+/** `LiquidityAmounts.getLiquidityForAmount0`. */
+export declare function getLiquidityForAmount0(sqrtRatioAX96: bigint, sqrtRatioBX96: bigint, amount0: bigint): bigint;
+/** `LiquidityAmounts.getLiquidityForAmount1`. */
+export declare function getLiquidityForAmount1(sqrtRatioAX96: bigint, sqrtRatioBX96: bigint, amount1: bigint): bigint;
+/** `LiquidityAmounts.getLiquidityForAmounts`. */
+export declare function getLiquidityForAmounts(sqrtRatioX96: bigint, sqrtRatioAX96: bigint, sqrtRatioBX96: bigint, amount0: bigint, amount1: bigint): bigint;
+/**
+ * Amounts the pool will move for a liquidity change spanning `sqrtRatioX96`.
+ *
+ * `adding` selects the rounding direction: the contracts round **towards the
+ * pool** either way, so an add costs one wei more and a remove returns one wei
+ * less than the unrounded figure.
+ */
+export declare function amountsForLiquidity(sqrtRatioX96: bigint, tickLower: number, tickUpper: number, liquidity: bigint, adding: boolean): {
+    amount0: bigint;
+    amount1: bigint;
+};
+/** Which tokens a CL range takes at the pool's current price. */
+export type ClRangeSide = "both" | "token0-only" | "token1-only";
+/**
+ * Which tokens a deposit into `[tickLower, tickUpper)` takes at `sqrtRatioX96`:
+ * a range entirely above the price holds only token0, one entirely below only
+ * token1, and a range spanning the price holds both in a ratio the price fixes.
+ */
+export declare function clRangeSide(sqrtRatioX96: bigint, tickLower: number, tickUpper: number): ClRangeSide;
+/**
+ * The other token's amount for a one-sided entry into an in-range CL
+ * position: the liquidity the entered amount buys, and what that liquidity
+ * costs of the other token (rounded up, as the position manager settles an
+ * add). `null` when the range takes only one token - the other side is then
+ * zero by construction, and no amount of it can be deposited.
+ */
+export declare function pairedAmountForRange(sqrtRatioX96: bigint, tickLower: number, tickUpper: number, entered: "token0" | "token1", amount: bigint): bigint | null;
+/** Fee growth recorded on one initialised tick (`Tick.Info`). */
+export interface TickFeeGrowth {
+    readonly feeGrowthOutside0X128: bigint;
+    readonly feeGrowthOutside1X128: bigint;
+}
+/**
+ * Fees a position has earned since it was last touched, exactly as
+ * `CLPosition.update` credits them on the next `modifyLiquidity`.
+ *
+ * All subtractions wrap at 2^256 on purpose: the pool's own arithmetic is
+ * `unchecked`, and fee-growth values are only meaningful modulo 2^256.
+ */
+export declare function uncollectedFees(args: {
+    readonly liquidity: bigint;
+    readonly tickLower: number;
+    readonly tickUpper: number;
+    readonly currentTick: number;
+    readonly feeGrowthGlobal0X128: bigint;
+    readonly feeGrowthGlobal1X128: bigint;
+    readonly lower: TickFeeGrowth;
+    readonly upper: TickFeeGrowth;
+    readonly feeGrowthInside0LastX128: bigint;
+    readonly feeGrowthInside1LastX128: bigint;
+}): {
+    fees0: bigint;
+    fees1: bigint;
+};
+/**
+ * Checks this transcription against values the chain publishes.
+ *
+ * @throws when the bit-magic constants have been corrupted.
+ */
+export declare function assertTickMathSelfConsistent(): void;
+//# sourceMappingURL=clMath.d.ts.map

package/dist/core/clMath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clMath.d.ts","sourceRoot":"","sources":["../../src/core/clMath.ts"],"names":[],"mappings":"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"}

package/dist/core/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Turns whatever a quote, a wallet or a transaction threw into one sentence a
+ * trader can read.
+ *
+ * The raw error stays on the hook results (`error`) for hosts and logs; this is
+ * only what the styled widgets PRINT. Nothing here invents a cause: a revert is
+ * decoded against the ABIs of the contracts the widgets actually call (router,
+ * quoters, position managers, launch guards, core), wrappers are unwrapped
+ * (core's `WrappedError`, the quoter's `UnexpectedRevertBytes`), and a known
+ * error name gets a plain explanation. An unknown selector is reported as what
+ * it is - an unrecognised refusal - never guessed at.
+ */
+import { type Hex } from "viem";
+/** Decodes revert data to an error name, following wrappers. `null` when unknown. */
+export declare function decodeRevertName(data: Hex, depth?: number): string | null;
+/** What went wrong, in one plain sentence. `context` names the action for the fallbacks. */
+export declare function describeError(error: unknown, context?: "quote" | "swap" | "liquidity" | "transaction"): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAoD,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAoJlF,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,SAAI,GAAG,MAAM,GAAG,IAAI,CAoBpE;AA8BD,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,OAAO,GAAG,MAAM,GAAG,WAAW,GAAG,aAA6B,GAAG,MAAM,CAoC7H"}

package/dist/core/format.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Display formatting and user-input parsing.
+ *
+ * Parsing is the security-relevant half: a mis-parsed decimal string becomes a
+ * wrong `amountIn`, and `parseUnits` will happily truncate extra decimal places.
+ * {@link parseAmount} refuses ambiguous input instead of guessing.
+ */
+/** A rejected amount string, with a reason suitable for showing to a user. */
+export interface AmountParseFailure {
+    readonly ok: false;
+    readonly reason: "empty" | "not-a-number" | "negative" | "too-many-decimals" | "zero";
+    readonly message: string;
+}
+/** A successfully parsed amount. */
+export interface AmountParseSuccess {
+    readonly ok: true;
+    readonly value: bigint;
+}
+export type AmountParseResult = AmountParseSuccess | AmountParseFailure;
+/**
+ * Parses a user-entered decimal string into the token's smallest unit.
+ *
+ * @param allowZero when `false` (default) a zero amount is rejected, since a
+ * zero-amount swap is never what the user meant.
+ */
+export declare function parseAmount(input: string, decimals: number, allowZero?: boolean): AmountParseResult;
+/**
+ * Formats a smallest-unit amount for display.
+ *
+ * Trims trailing zeros and caps the visible fraction, but never rounds a value
+ * up to a non-zero display when it is zero, and never shows `0` for a non-zero
+ * dust amount - it shows `<0.0001` instead.
+ */
+export declare function formatAmount(value: bigint, decimals: number, maxFractionDigits?: number): string;
+/** Formats a rate for display, e.g. `1 A = 1,234.5678 B`. */
+export declare function formatRate(rate: number | null, symbolIn: string, symbolOut: string): string;
+/** Formats a bps value as a percentage string. */
+export declare function formatPercentFromBps(bps: number | null): string;
+/** Formats a pips value (1e6 = 100%) as a percentage string. */
+export declare function formatPercentFromPips(pips: number): string;
+/** Shortens an address for display: `0x1234...cdef`. */
+export declare function shortAddress(address: string): string;
+/** Formats a remaining duration in seconds as a compact `1d 4h 3m` string. */
+export declare function formatDuration(totalSeconds: number): string;
+/** Formats a unix timestamp for display in the viewer's locale. */
+export declare function formatTimestamp(unixSeconds: bigint | number): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/core/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/core/format.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAIH,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EACX,OAAO,GACP,cAAc,GACd,UAAU,GACV,mBAAmB,GACnB,MAAM,CAAC;IACX,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,oCAAoC;AACpC,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAIxE;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,SAAS,UAAQ,GAChB,iBAAiB,CAwBnB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,iBAAiB,SAAI,GACpB,MAAM,CAmBR;AAMD,6DAA6D;AAC7D,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,MAAM,CAMR;AAED,kDAAkD;AAClD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAK/D;AAED,gEAAgE;AAChE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI1D;AAMD,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAa3D;AAED,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAIpE"}

package/dist/core/liquidityGuards.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Pure guards for the liquidity flow: what a deposit will take from the wallet,
+ * and whether the wallet holds it.
+ *
+ * WHY THIS EXISTS. Without it an add that the wallet cannot pay reaches gas
+ * estimation and comes back as `TRANSFER_FROM_FAILED` (or an out-of-funds
+ * error for native), after the visitor may already have signed an approval
+ * for tokens they do not hold. The widget checks the balances first and says
+ * "Insufficient <SYMBOL>" before anything is signed.
+ *
+ * WHAT IS COMPARED, exactly:
+ *   - native: the transaction's `value`, which is the side's slippage-bounded
+ *     MAXIMUM (the adapter sends the whole cap and the position manager refunds
+ *     the rest). No gas reserve is invented on top: the wallet refuses a
+ *     transaction it cannot pay gas for, and a made-up margin would refuse
+ *     deposits that fit.
+ *   - ERC-20: the QUOTED amount, which is what the position manager pulls at
+ *     the current price. The slippage cap is only an allowance ceiling; a wallet
+ *     holding the quoted amount but not the cap can still deposit.
+ */
+import type { TokenInfo } from "../adapters/protocol.js";
+/** True for the chain's native asset. */
+export declare function isNativeToken(token: TokenInfo): boolean;
+/** One side of a deposit: the token and what the wallet must hold of it. */
+export interface DepositRequirement {
+    readonly token: TokenInfo;
+    readonly required: bigint;
+}
+/**
+ * What an add-liquidity takes from the wallet, per token, in pool order. A side
+ * that deposits nothing is left out.
+ */
+export declare function depositRequirements(quote: {
+    readonly pool: {
+        readonly token0: TokenInfo;
+        readonly token1: TokenInfo;
+    };
+    readonly amount0: bigint;
+    readonly amount1: bigint;
+}, amount0Max: bigint, amount1Max: bigint): readonly DepositRequirement[];
+/**
+ * The first token the wallet holds too little of, or `null` when every balance
+ * covers its requirement. `balances[i]` is the wallet's balance of
+ * `requirements[i].token`; a `null` balance (not read) is never reported as a
+ * shortfall - the widget does not claim what it has not read.
+ */
+export declare function findShortfall(requirements: readonly DepositRequirement[], balances: readonly (bigint | null)[]): TokenInfo | null;
+/** Refusal raised before an approval or a deposit the wallet cannot pay. Nothing was signed. */
+export declare class InsufficientBalanceError extends Error {
+    readonly token: TokenInfo;
+    constructor(token: TokenInfo);
+}
+//# sourceMappingURL=liquidityGuards.d.ts.map

package/dist/core/liquidityGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liquidityGuards.d.ts","sourceRoot":"","sources":["../../src/core/liquidityGuards.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,yCAAyC;AACzC,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAEvD;AAED,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE;IACL,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;KAAE,CAAC;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,EACD,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,SAAS,kBAAkB,EAAE,CAS/B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,SAAS,kBAAkB,EAAE,EAC3C,QAAQ,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GACnC,SAAS,GAAG,IAAI,CAMlB;AAED,gGAAgG;AAChG,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;gBAEd,KAAK,EAAE,SAAS;CAK7B"}

package/dist/core/liquidityRefresh.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Keeping the liquidity widget's own lists true after a confirmed add or
+ * removal, without a reload.
+ *
+ * The widget counts confirmed changes (`bumpOnConfirmed`); the positions list,
+ * the pool state and the wallet balances take that count as a dependency, so a
+ * confirmation re-reads them. The picker then re-selects from the FRESH list
+ * (`reconcileSelection`), so a partial removal shows the new amounts and a
+ * position emptied to zero disappears (`withdrawablePositions`).
+ */
+import type { PositionInfo } from "../adapters/protocol.js";
+/**
+ * Wraps the host's `onLiquidityChanged` so a confirmation also advances the
+ * widget's refresh counter. The counter moves first: the host's callback can
+ * throw without leaving the widget's lists stale.
+ */
+export declare function bumpOnConfirmed<H>(bump: () => void, host: ((hash: H) => void) | undefined): (hash: H) => void;
+/**
+ * The positions there is something to withdraw from. A CL position removed to
+ * zero keeps its NFT (the widget decreases liquidity and takes the tokens; it
+ * does not burn), so the adapter still lists it with zero liquidity and zero
+ * owed fees - offering it in the Remove picker would quote a withdrawal of
+ * nothing.
+ */
+export declare function withdrawablePositions(list: readonly PositionInfo[]): readonly PositionInfo[];
+/**
+ * The selection after the list was re-read: the SAME position as its fresh
+ * record (new amounts, new liquidity), else the first position, else `null`.
+ * Returning the fresh object matters - a stale one keeps quoting the
+ * withdrawal against the liquidity it had before the last removal.
+ */
+export declare function reconcileSelection<T extends {
+    readonly id: string;
+}>(current: T | null, list: readonly T[]): T | null;
+//# sourceMappingURL=liquidityRefresh.d.ts.map

package/dist/core/liquidityRefresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liquidityRefresh.d.ts","sourceRoot":"","sources":["../../src/core/liquidityRefresh.ts"],"names":[],"mappings":"AACA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,IAAI,EAAE,MAAM,IAAI,EAChB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,GACpC,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAKnB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,YAAY,EAAE,CAE5F;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,GAAG,IAAI,CAMrH"}

package/dist/core/math.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Quote arithmetic.
+ *
+ * Everything here is pure, integer-only and independent of any chain, adapter
+ * or component, so it can be tested exhaustively. The rounding directions match
+ * the contracts: fees and minimum-received amounts round **down**, maximum-spend
+ * amounts round **up**. Every rounding error is therefore in the user's favour
+ * or, at worst, causes a revert instead of a silent loss.
+ */
+import { type ResolvedIntegratorConfig } from "../config/integrator.js";
+/** Basis-point denominator as a bigint. */
+export declare const BPS = 10000n;
+/** Pips denominator, matching `ProtocolFeeLibrary.PIPS_DENOMINATOR`. */
+export declare const PIPS = 1000000n;
+/**
+ * Highest slippage tolerance the widgets accept, in bps (50%).
+ *
+ * Above this a "swap" is indistinguishable from a donation to whoever is
+ * watching the mempool.
+ */
+export declare const MAX_SLIPPAGE_BPS = 5000;
+/** Slippage used when the embedder sets none. */
+export declare const DEFAULT_SLIPPAGE_BPS = 50;
+/** Price impact at or above which the UI demands explicit confirmation. */
+export declare const HIGH_PRICE_IMPACT_BPS = 300;
+/** Price impact treated as certainly-a-mistake. */
+export declare const SEVERE_PRICE_IMPACT_BPS = 1000;
+/** `floor(amount * bps / 10_000)`. */
+export declare function portionOf(amount: bigint, bps: number): bigint;
+/** `floor(amount * pips / 1_000_000)`. */
+export declare function pipsOf(amount: bigint, pips: number): bigint;
+/**
+ * Minimum amount that must be received for the transaction to be acceptable.
+ *
+ * Rounds down, so the on-chain check is never tighter than the user's stated
+ * tolerance.
+ */
+export declare function minimumReceived(expected: bigint, slippageBps: number): bigint;
+/**
+ * Maximum amount the user is willing to spend.
+ *
+ * Rounds up, so a one-wei rounding difference on-chain does not revert an
+ * otherwise valid exact-output swap.
+ */
+export declare function maximumSpent(expected: bigint, slippageBps: number): bigint;
+/**
+ * Price impact in basis points: how much worse the realised rate is than the
+ * pool's rate for an infinitesimal trade.
+ *
+ * `spotAmountOut` is what the same input would return at the current price with
+ * no impact and no LP fee. Returns `null` when that reference is unavailable or
+ * zero, because a fabricated zero would read as "no impact" - the most
+ * dangerous possible default.
+ */
+export declare function priceImpactBps(grossAmountOut: bigint, spotAmountOut: bigint | null | undefined): number | null;
+/** Severity buckets for a price impact, used for presentation and gating. */
+export type PriceImpactSeverity = "unknown" | "low" | "elevated" | "high" | "severe";
+/** Classifies a price impact in bps. */
+export declare function priceImpactSeverity(bps: number | null): PriceImpactSeverity;
+/** Inputs to {@link buildQuoteBreakdown}. */
+export interface QuoteBreakdownInput {
+    /** Input amount, in the input currency's smallest unit. */
+    readonly amountIn: bigint;
+    /** Output before any integrator fee, as returned by the adapter. */
+    readonly grossAmountOut: bigint;
+    /** Output at the current price with no impact, if the adapter can supply it. */
+    readonly spotAmountOut?: bigint | null;
+    /** LP fee already deducted by the pool, in the output currency. */
+    readonly lpFeeAmount?: bigint;
+    /** Pool's LP fee rate in pips. */
+    readonly lpFeePips?: number;
+    /** The rate is hook-set and was not readable; `lpFeePips` is a placeholder zero. */
+    readonly lpFeeUnknown?: boolean;
+    /** User's slippage tolerance. */
+    readonly slippageBps: number;
+    /** Validated integrator config. */
+    readonly integrator: ResolvedIntegratorConfig;
+}
+/**
+ * Everything a swap UI and a swap call path need, derived once.
+ *
+ * The two minimums matter and are not interchangeable:
+ *
+ * - `minAmountOutGross` is checked by the swap action, before the fee is split.
+ * - `minAmountOutNet` is what the user is guaranteed to actually receive, and is
+ *   the value the final take/sweep enforces.
+ */
+export interface QuoteBreakdown {
+    readonly amountIn: bigint;
+    readonly grossAmountOut: bigint;
+    readonly integratorFee: bigint;
+    readonly integratorFeeBps: number;
+    readonly netAmountOut: bigint;
+    readonly minAmountOutGross: bigint;
+    readonly minAmountOutNet: bigint;
+    readonly lpFeeAmount: bigint;
+    readonly lpFeePips: number;
+    /** See {@link QuoteBreakdownInput.lpFeeUnknown}. Render as "dynamic", never as a percentage. */
+    readonly lpFeeUnknown: boolean;
+    readonly slippageBps: number;
+    readonly priceImpactBps: number | null;
+    readonly priceImpactSeverity: PriceImpactSeverity;
+}
+/**
+ * Derives the full quote breakdown.
+ *
+ * `minAmountOutNet` is computed as `minGross - portion(minGross)` rather than
+ * `portion(netAmountOut)`. That matters: the fee is taken on-chain from the
+ * *realised* output, not the quoted one, and `x - floor(x * bps / 10_000)` is
+ * monotonically non-decreasing in `x`. So this is a genuine floor on what the
+ * user receives whenever the swap itself clears `minAmountOutGross`.
+ */
+export declare function buildQuoteBreakdown(input: QuoteBreakdownInput): QuoteBreakdown;
+/**
+ * Exchange rate as a floating-point number of output units per input unit.
+ *
+ * Display only. Never feed this back into a call path - it loses precision by
+ * construction.
+ */
+export declare function exchangeRate(amountIn: bigint, decimalsIn: number, amountOut: bigint, decimalsOut: number): number | null;
+/** Progress of a sale as a percentage in `[0, 100]`. */
+export declare function progressPercent(sold: bigint, total: bigint): number;
+/** Clamps `value` to `[min, max]`. */
+export declare function clampBigInt(value: bigint, min: bigint, max: bigint): bigint;
+/** Rounds a tick down to the nearest usable multiple of `tickSpacing`. */
+export declare function floorTickToSpacing(tick: number, tickSpacing: number): number;
+/** Rounds a tick up to the nearest usable multiple of `tickSpacing`. */
+export declare function ceilTickToSpacing(tick: number, tickSpacing: number): number;
+//# sourceMappingURL=math.d.ts.map

package/dist/core/math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../../src/core/math.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAEH,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,yBAAyB,CAAC;AAEjC,2CAA2C;AAC3C,eAAO,MAAM,GAAG,SAAU,CAAC;AAE3B,wEAAwE;AACxE,eAAO,MAAM,IAAI,WAAa,CAAC;AAE/B;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,OAAQ,CAAC;AAEtC,iDAAiD;AACjD,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,mDAAmD;AACnD,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAY7C,sCAAsC;AACtC,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,0CAA0C;AAC1C,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI3D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAI7E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACvC,MAAM,GAAG,IAAI,CAMf;AAED,6EAA6E;AAC7E,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;AAErF,wCAAwC;AACxC,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,mBAAmB,CAM3E;AAED,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,gFAAgF;IAChF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oFAAoF;IACpF,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mCAAmC;IACnC,QAAQ,CAAC,UAAU,EAAE,wBAAwB,CAAC;CAC/C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gGAAgG;IAChG,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,mBAAmB,EAAE,mBAAmB,CAAC;CACnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,cAAc,CA6B9E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAMf;AAED,wDAAwD;AACxD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAInE;AAED,sCAAsC;AACtC,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAK3E;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAK5E;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAK3E"}

package/dist/core/pool.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What a pool key already says about a pool.
+ *
+ * `PoolInfo.tickSpacing` and `PoolInfo.binStep` are optional because a host
+ * that lists pools from an indexer may not fill them in - but both live in the
+ * key's `parameters` word, so nothing needs to guess. These read the key when
+ * the field is absent, and every range editor and quote goes through them.
+ */
+import { type PoolId } from "@latchprotocol/sdk";
+import type { PoolInfo } from "../adapters/protocol.js";
+/** The tick spacing of a concentrated-liquidity pool, from the info or its key. */
+export declare function tickSpacingOf(pool: PoolInfo): number;
+/** The bin step of a liquidity-book pool, from the info or its key. */
+export declare function binStepOf(pool: PoolInfo): number;
+/**
+ * `BinTokenLibrary.toTokenId`: the fungible token id `BinPositionManager`
+ * mints for one bin of one pool, `keccak256(abi.encode(poolId, binId))`.
+ */
+export declare function binTokenId(poolId: PoolId, binId: number): bigint;
+/**
+ * The reserves a holder's shares of one bin are worth right now, rounded
+ * DOWN exactly as `BinPool.burn` computes them (`amount * shares / totalShares`).
+ */
+export declare function binShareAmounts(args: {
+    readonly shares: bigint;
+    readonly totalShares: bigint;
+    readonly reserveX: bigint;
+    readonly reserveY: bigint;
+}): {
+    amount0: bigint;
+    amount1: bigint;
+};
+//# sourceMappingURL=pool.d.ts.map

package/dist/core/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/core/pool.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAOH,OAAO,EAAqD,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACpG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAGpD;AAED,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAGhD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAShE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAMvC"}

package/dist/core/tokenLists.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Token lists as the picker consumes them: pure functions from the SDK's
+ * `TokenList` documents to the widgets' `TokenInfo`, with the provenance kept
+ * on each entry. The React hook (`hooks/useTokenLists.ts`) fetches and calls
+ * these; nothing here touches the network or the DOM, so it is testable on its
+ * own and reusable by a headless integrator.
+ */
+import { type MergedTokenList, type TokenList } from "@latchprotocol/sdk";
+import type { TokenInfo } from "../adapters/protocol.js";
+/** One entry of `SwapWidget`'s `tokenLists`: a list already in hand, or a URL to fetch. */
+export type TokenListInput = TokenList | {
+    readonly url: string;
+};
+export declare function isTokenListUrl(input: TokenListInput): input is {
+    readonly url: string;
+};
+/**
+ * The picker entries a merge yields, for `chainId`. Tokens whose address is not
+ * a 20-byte hex address (the schema also admits a Solana form) are skipped:
+ * they cannot be a Latch pool currency.
+ */
+export declare function tokensFromMergedList(merged: MergedTokenList): readonly TokenInfo[];
+/**
+ * The picker's final order: the adapter's own tokens first (the tokens of the
+ * pools this site routes through, read on chain), then every list's tokens in
+ * list order, deduped by lowercase address. A token the adapter already knows
+ * keeps the adapter's fields — its decimals were read off the contract — and
+ * gains the list's provenance, logo, stock badge and tags where the adapter had
+ * none.
+ */
+export declare function combineTokens(adapterTokens: readonly TokenInfo[], listTokens: readonly TokenInfo[]): readonly TokenInfo[];
+/** `mergeTokenLists` then `tokensFromMergedList`, for callers with every list in hand. */
+export declare function tokensFromLists(lists: readonly TokenList[], chainId: number): readonly TokenInfo[];
+/**
+ * The URL an `<img>` can load for a token's logo: `https://` as given,
+ * `ipfs://` through the SDK's first allow-listed gateway, anything else
+ * `null` (the caller draws a monogram). `http://` is refused: a mixed-content
+ * image on an https site is blocked by the browser and reads as a broken logo.
+ */
+export declare function resolveLogoUrl(logoUrl: string | undefined, gateways?: readonly string[]): string | null;
+/** Group entries by their list source, in first-seen order; adapter tokens (no source) come first under `null`. */
+export declare function groupBySource(tokens: readonly TokenInfo[]): readonly {
+    readonly source: string | null;
+    readonly tokens: readonly TokenInfo[];
+}[];
+//# sourceMappingURL=tokenLists.d.ts.map

package/dist/core/tokenLists.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenLists.d.ts","sourceRoot":"","sources":["../../src/core/tokenLists.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,SAAS,EACf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,2FAA2F;AAC3F,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,KAAK,IAAI;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAEvF;AAID;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,SAAS,EAAE,CAmBlF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,aAAa,EAAE,SAAS,SAAS,EAAE,EAAE,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,SAAS,EAAE,CAsBzH;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,SAAS,EAAE,CAElG;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAQvG;AAED,mHAAmH;AACnH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;CAAE,EAAE,CAUhJ"}