@logswap/sdk 0.5.35

package/dist/liquidity.d.ts

@@ -0,0 +1,223 @@
+/**
+ * liquidity.ts — providing, editing and exiting a C position.
+ *
+ * A class is (ξ, μ, L): floor, cap, exposure. One primitive sets all three — `update` — and every
+ * edit is a constraint on it. The vocabulary follows the geometry (decisions 009): **the verb
+ * names the axis, the direction is a signed rung count**, and only two direction-words survive,
+ * because each names a wallet flow the user must see.
+ *
+ *   update(ξ', μ', L')     the primitive
+ *   ├─ move(ξ', μ')        L pinned
+ *   │   ├─ floor(±n)       μ pinned  · ↑ harvest (receive quote) · ↓ deepen (pay quote)
+ *   │   ├─ cap(±n)         ξ pinned  · no direction words
+ *   │   └─ shift(±n)       width pinned — the translation
+ *   ├─ resize(L')          ξ, μ pinned; L' = 0 is the exit
+ *   └─ reprice(ξ')         R pinned: L' = L·e^{ξ' − ξ}, dormant only
+ *   mint · burn · claim
+ *
+ * Every edit is ONE action of the router's batch (decisions 010, `actions.ts`), which is what
+ * lets it settle in kind, or in base, or in quote: `settleIn` appends the one swap that nets the
+ * other side, and the batch moves a single token. `previewEdit` is the lens's `previewUpdate` —
+ * the exact flows, mint fee and swept fees included — and is what an editor shows before its one
+ * apply.
+ */
+import type { Address, Hash } from "viem";
+import type { LogswapClient } from "./client.js";
+import type { PoolKey } from "./keys.js";
+import { type PairBounds } from "./actions.js";
+import { type WriteOptions } from "./write.js";
+export interface MintArgs extends WriteOptions {
+    key: PoolKey;
+    /** Log-price floor. Need not be on the grid — see the blending note below. */
+    targetFloor: bigint;
+    cap?: bigint;
+    /** Exposure to add. */
+    L: bigint;
+    maxBaseIn?: bigint;
+    maxQuoteIn?: bigint;
+}
+/**
+ * Mint at `targetFloor`, blending across the two adjacent rungs when it is off-grid.
+ *
+ * This is why the floor ladder can be coarse without the UX being coarse: a blend of two adjacent
+ * classes IS exactly one position at the weighted-mean floor, so a continuous floor slider works
+ * over a discrete ladder. The router settles once per token, not once per rung.
+ *
+ * **A mint at floor == spot costs zero quote** ($Q(\xi) = 0$), and one above spot is dormant and
+ * costs zero quote too — that is what makes single-asset entry possible in both directions.
+ */
+export declare function mint(c: LogswapClient, a: MintArgs): Promise<Hash>;
+export interface CreateMarketArgs extends WriteOptions {
+    key: PoolKey;
+    /** Launch log-price. Bounded by the manager to ±46 (the price domain, decisions 012). */
+    x0: bigint;
+    /** The backstop's floor — the first mint's rung, permanent for the pool's life. */
+    targetFloor: bigint;
+    /** The founding exposure; must exceed the manager's `minBackstopL` lock. */
+    L: bigint;
+    maxBaseIn?: bigint;
+    maxQuoteIn?: bigint;
+}
+/**
+ * Create a market ATOMICALLY: `initialize` at `x0` plus the backstop-establishing first mint in
+ * one transaction — the canonical creation path (decisions 013, security-review H-02). The
+ * two-step path let an attacker seat the PERMANENT backstop at a hostile rung between an honest
+ * `initialize` and its first mint; here either both land or neither, and a front-run of the whole
+ * call reverts it without moving a wei. No cap: the first mint IS the backstop and must be
+ * uncapped.
+ */
+export declare function createMarket(c: LogswapClient, a: CreateMarketArgs): Promise<Hash>;
+export interface ZapArgs extends WriteOptions {
+    key: PoolKey;
+    /** Fund entirely from base (true) or entirely from quote (false). */
+    fundWithBase: boolean;
+    amountIn: bigint;
+    targetFloor: bigint;
+    cap?: bigint;
+    L: bigint;
+    maxIn?: bigint;
+}
+/**
+ * Fund a mint from a single asset: the router swaps the imbalanced part through the curve, then
+ * mints, all inside one lock — the two-action batch `[swapExactIn, mint]`.
+ *
+ * Routing the imbalanced part through the CURVE is the point, not an implementation detail. A
+ * pro-rata deposit of one asset would be a zero-slippage, zero-fee swap at stale spot — a subsidy
+ * paid by the incumbent LPs (`logswap-docs` §*Quote-only capital*). Paying the curve removes it.
+ */
+export declare function zapIn(c: LogswapClient, a: ZapArgs): Promise<Hash>;
+export interface UpdateArgs extends WriteOptions {
+    key: PoolKey;
+    fromId: bigint;
+    shares: bigint;
+    toFloor: bigint;
+    toCap?: bigint;
+    /** New exposure. `0n` exits the position entirely. */
+    newL: bigint;
+    maxBaseIn?: bigint;
+    maxQuoteIn?: bigint;
+}
+/** The primitive, through the router's named entry: resize and reposition in one call, in kind. */
+export declare function update(c: LogswapClient, a: UpdateArgs): Promise<Hash>;
+export interface MoveArgs extends WriteOptions {
+    key: PoolKey;
+    fromId: bigint;
+    shares: bigint;
+    toFloor: bigint;
+    toCap?: bigint;
+    maxBaseIn?: bigint;
+    maxQuoteIn?: bigint;
+}
+/**
+ * Reposition at constant exposure — the L-pinned parent of `floor`, `cap` and `shift`; in kind.
+ *
+ * **Bound it.** The router used to settle this entry with no limit, which meant a reposition that
+ * priced differently by inclusion time could pull the whole allowance (security-review2 M-01).
+ * The defaults below are unbounded for callers who genuinely want that; pass `maxBaseIn` /
+ * `maxQuoteIn` from a preview for anything user-facing.
+ */
+export declare function move(c: LogswapClient, a: MoveArgs): Promise<Hash>;
+/** Which token the edit settles in. `kind` moves both legs; `base` / `quote` nets the other side through the curve. */
+export type SettleIn = "kind" | "base" | "quote";
+export interface EditArgs extends WriteOptions, PairBounds {
+    key: PoolKey;
+    fromId: bigint;
+    /** The shares to edit — all of a holding, or part of it. */
+    shares: bigint;
+    /** Default `kind`. */
+    settleIn?: SettleIn;
+}
+export interface EditPreview {
+    /** Signed, + = the caller deposits; the mint fee is inside `dQuote`. */
+    dBase: bigint;
+    dQuote: bigint;
+    /** Accrued fees the edit sweeps, delivered in the same settlement. */
+    fees: bigint;
+}
+/** The exact flows of an edit before it is sent — the lens's `previewUpdate`. */
+export declare function previewEdit(c: LogswapClient, a: {
+    key: PoolKey;
+    fromId: bigint;
+    holder?: Address;
+    shares: bigint;
+    toFloor: bigint;
+    toCap?: bigint;
+    newL: bigint;
+}): Promise<EditPreview>;
+/**
+ * The general edit as a batch: `[update]`, plus — when `settleIn` is one token — the one swap that
+ * nets the other. The other side's flow is read off the preview: released → sold with an exact-in
+ * of `OPEN_DELTA`; owed → bought with an exact-out of `OPEN_DELTA`. The settlement then binds the
+ * other token to zero both ways, so a stale preview fails loudly rather than moving it.
+ */
+export declare function edit(c: LogswapClient, a: EditArgs & {
+    toFloor: bigint;
+    toCap?: bigint;
+    newL: bigint;
+}): Promise<Hash>;
+/** Move the floor by `rungs` (signed), cap and L pinned. Positive = harvest, negative = deepen. */
+export declare function floor(c: LogswapClient, a: EditArgs & {
+    rungs: bigint;
+}): Promise<Hash>;
+/**
+ * Raise the floor by `rungs` (default 1) and withdraw PURE QUOTE — the base leg untouched.
+ *
+ * A burn is in kind: it returns base and quote pro rata, so taking α of the proceeds also takes α
+ * of the unsold inventory off the market. Raising the floor instead releases
+ *
+ *   ΔQ = L (ξ' − ξ),   ΔR = 0
+ *
+ * because $R = Le^{-x}$ depends on neither the floor nor the withdrawal. No base moves, the price
+ * does not move, and depth is unchanged. **The cost, which a UI must show:** the position stops
+ * bidding below ξ'. `settleIn: "base"` swaps the proceeds into base in the same batch.
+ */
+export declare function harvest(c: LogswapClient, a: EditArgs & {
+    rungs?: bigint;
+}): Promise<Hash>;
+/**
+ * Lower the floor by `rungs` (default 1), paying L·Δξ of quote for the deeper bid — harvest's
+ * mirror. `settleIn: "base"` pays it in base instead (an exact-out of the quote owed).
+ */
+export declare function deepen(c: LogswapClient, a: EditArgs & {
+    rungs?: bigint;
+}): Promise<Hash>;
+/** Move the cap by `rungs` (signed), floor and L pinned. Base flows while the class converts; quote once capped out. */
+export declare function cap(c: LogswapClient, a: EditArgs & {
+    rungs: bigint;
+}): Promise<Hash>;
+/** Translate the class by `rungs` (signed): floor and cap together, width and L pinned. */
+export declare function shift(c: LogswapClient, a: EditArgs & {
+    rungs: bigint;
+}): Promise<Hash>;
+/** Set the exposure to `newL`, floor and cap pinned; both legs pro rata. The mint fee bites on an increase only. */
+export declare function resize(c: LogswapClient, a: EditArgs & {
+    newL: bigint;
+}): Promise<Hash>;
+/** Exit `shares` — `resize(0)`. `settleIn: "quote"` (or `"base"`) leaves with one asset. */
+export declare function exit(c: LogswapClient, a: EditArgs): Promise<Hash>;
+/**
+ * Re-express a DORMANT class's base at a new trigger price: the base is pinned, so
+ * L' = L·e^{ξ' − ξ} and nothing moves but the trigger. `toFloor` must stay above spot.
+ *
+ * The exponential is evaluated in double precision (~1e-16 relative), which is far inside the
+ * wei-rounding of the class it produces; an exact L' is not what a trigger edit is about.
+ */
+export declare function reprice(c: LogswapClient, a: EditArgs & {
+    toFloor: bigint;
+}): Promise<Hash>;
+/** Quote released by a harvest, exactly: ΔQ = L(ξ' − ξ). Base is untouched. */
+export declare function harvestProceeds(L: bigint, fromFloor: bigint, toFloor: bigint): bigint;
+export interface BurnArgs extends WriteOptions {
+    key: PoolKey;
+    ids: readonly bigint[];
+    shares: readonly bigint[];
+    minBaseOut?: bigint;
+    minQuoteOut?: bigint;
+}
+/**
+ * Exit, in kind, across one or more classes. Accrued fees are swept into the same settlement.
+ *
+ * In kind means both legs, pro rata. To take proceeds while leaving inventory in the market, that
+ * is {@link harvest}; to leave with one asset, {@link exit} with `settleIn`.
+ */
+export declare function burn(c: LogswapClient, a: BurnArgs): Promise<Hash>;

package/dist/liquidity.js

@@ -0,0 +1,305 @@
+/**
+ * liquidity.ts — providing, editing and exiting a C position.
+ *
+ * A class is (ξ, μ, L): floor, cap, exposure. One primitive sets all three — `update` — and every
+ * edit is a constraint on it. The vocabulary follows the geometry (decisions 009): **the verb
+ * names the axis, the direction is a signed rung count**, and only two direction-words survive,
+ * because each names a wallet flow the user must see.
+ *
+ *   update(ξ', μ', L')     the primitive
+ *   ├─ move(ξ', μ')        L pinned
+ *   │   ├─ floor(±n)       μ pinned  · ↑ harvest (receive quote) · ↓ deepen (pay quote)
+ *   │   ├─ cap(±n)         ξ pinned  · no direction words
+ *   │   └─ shift(±n)       width pinned — the translation
+ *   ├─ resize(L')          ξ, μ pinned; L' = 0 is the exit
+ *   └─ reprice(ξ')         R pinned: L' = L·e^{ξ' − ξ}, dormant only
+ *   mint · burn · claim
+ *
+ * Every edit is ONE action of the router's batch (decisions 010, `actions.ts`), which is what
+ * lets it settle in kind, or in base, or in quote: `settleIn` appends the one swap that nets the
+ * other side, and the batch moves a single token. `previewEdit` is the lens's `previewUpdate` —
+ * the exact flows, mint fee and swept fees included — and is what an editor shows before its one
+ * apply.
+ */
+import { logswapLensAbi, logswapRouterAbi } from "./generated.js";
+import { NO_CAP } from "./ids.js";
+import { describeId, getPositionClass } from "./positions.js";
+import { execute, OPEN_DELTA, settleInKind, settleOnly, swapExactInAction, swapExactOutAction, updateAction, } from "./actions.js";
+import { requireWallet, resolveDeadline, resolveRecipient, sendRouterWrite, sendRouterWriteWithPermits, } from "./write.js";
+/**
+ * Mint at `targetFloor`, blending across the two adjacent rungs when it is off-grid.
+ *
+ * This is why the floor ladder can be coarse without the UX being coarse: a blend of two adjacent
+ * classes IS exactly one position at the weighted-mean floor, so a continuous floor slider works
+ * over a discrete ladder. The router settles once per token, not once per rung.
+ *
+ * **A mint at floor == spot costs zero quote** ($Q(\xi) = 0$), and one above spot is dormant and
+ * costs zero quote too — that is what makes single-asset entry possible in both directions.
+ */
+export async function mint(c, a) {
+    const MAX = (1n << 256n) - 1n;
+    return sendRouterWriteWithPermits(c, {
+        abi: logswapRouterAbi,
+        functionName: "mintBlended",
+        args: [
+            a.key,
+            a.targetFloor,
+            a.cap ?? NO_CAP,
+            a.L,
+            a.maxBaseIn ?? MAX,
+            a.maxQuoteIn ?? MAX,
+            resolveRecipient(c, a),
+            resolveDeadline(a),
+        ],
+    }, [a.key.base, a.key.quote]);
+}
+/**
+ * Create a market ATOMICALLY: `initialize` at `x0` plus the backstop-establishing first mint in
+ * one transaction — the canonical creation path (decisions 013, security-review H-02). The
+ * two-step path let an attacker seat the PERMANENT backstop at a hostile rung between an honest
+ * `initialize` and its first mint; here either both land or neither, and a front-run of the whole
+ * call reverts it without moving a wei. No cap: the first mint IS the backstop and must be
+ * uncapped.
+ */
+export async function createMarket(c, a) {
+    const MAX = (1n << 256n) - 1n;
+    return sendRouterWriteWithPermits(c, {
+        abi: logswapRouterAbi,
+        functionName: "createMarket",
+        args: [
+            a.key,
+            a.x0,
+            a.targetFloor,
+            a.L,
+            a.maxBaseIn ?? MAX,
+            a.maxQuoteIn ?? MAX,
+            resolveRecipient(c, a),
+            resolveDeadline(a),
+        ],
+    }, [a.key.base, a.key.quote]);
+}
+/**
+ * Fund a mint from a single asset: the router swaps the imbalanced part through the curve, then
+ * mints, all inside one lock — the two-action batch `[swapExactIn, mint]`.
+ *
+ * Routing the imbalanced part through the CURVE is the point, not an implementation detail. A
+ * pro-rata deposit of one asset would be a zero-slippage, zero-fee swap at stale spot — a subsidy
+ * paid by the incumbent LPs (`logswap-docs` §*Quote-only capital*). Paying the curve removes it.
+ */
+export async function zapIn(c, a) {
+    return sendRouterWriteWithPermits(c, {
+        abi: logswapRouterAbi,
+        functionName: "zapIn",
+        args: [
+            a.key,
+            a.fundWithBase,
+            a.amountIn,
+            a.targetFloor,
+            a.cap ?? NO_CAP,
+            a.L,
+            a.maxIn ?? (1n << 256n) - 1n,
+            resolveRecipient(c, a),
+            resolveDeadline(a),
+        ],
+    }, [a.fundWithBase ? a.key.base : a.key.quote]);
+}
+/** The primitive, through the router's named entry: resize and reposition in one call, in kind. */
+export async function update(c, a) {
+    const MAX = (1n << 256n) - 1n;
+    return sendRouterWriteWithPermits(c, {
+        abi: logswapRouterAbi,
+        functionName: "update",
+        args: [
+            a.key,
+            a.fromId,
+            a.shares,
+            a.toFloor,
+            a.toCap ?? NO_CAP,
+            a.newL,
+            a.maxBaseIn ?? MAX,
+            a.maxQuoteIn ?? MAX,
+            resolveRecipient(c, a),
+            resolveDeadline(a),
+        ],
+    }, [a.key.base, a.key.quote]);
+}
+/**
+ * Reposition at constant exposure — the L-pinned parent of `floor`, `cap` and `shift`; in kind.
+ *
+ * **Bound it.** The router used to settle this entry with no limit, which meant a reposition that
+ * priced differently by inclusion time could pull the whole allowance (security-review2 M-01).
+ * The defaults below are unbounded for callers who genuinely want that; pass `maxBaseIn` /
+ * `maxQuoteIn` from a preview for anything user-facing.
+ */
+export async function move(c, a) {
+    const MAX = (1n << 256n) - 1n;
+    return sendRouterWrite(c, {
+        abi: logswapRouterAbi,
+        functionName: "move",
+        args: [
+            a.key,
+            a.fromId,
+            a.shares,
+            a.toFloor,
+            a.toCap ?? NO_CAP,
+            a.maxBaseIn ?? MAX,
+            a.maxQuoteIn ?? MAX,
+            resolveRecipient(c, a),
+            resolveDeadline(a),
+        ],
+    });
+}
+/** The exact flows of an edit before it is sent — the lens's `previewUpdate`. */
+export async function previewEdit(c, a) {
+    const holder = a.holder ?? requireWallet(c).address;
+    const r = (await c.public.readContract({
+        address: c.addresses.lens,
+        abi: logswapLensAbi,
+        functionName: "previewUpdate",
+        args: [a.key, a.fromId, holder, a.shares, a.toFloor, a.toCap ?? NO_CAP, a.newL],
+    }));
+    return { dBase: r[0], dQuote: r[1], fees: r[2] };
+}
+/**
+ * The general edit as a batch: `[update]`, plus — when `settleIn` is one token — the one swap that
+ * nets the other. The other side's flow is read off the preview: released → sold with an exact-in
+ * of `OPEN_DELTA`; owed → bought with an exact-out of `OPEN_DELTA`. The settlement then binds the
+ * other token to zero both ways, so a stale preview fails loudly rather than moving it.
+ */
+export async function edit(c, a) {
+    const { key } = a;
+    const recipient = resolveRecipient(c, a);
+    const actions = [
+        updateAction({ key, fromId: a.fromId, shares: a.shares, toFloor: a.toFloor, toCap: a.toCap, newL: a.newL }),
+    ];
+    const settleIn = a.settleIn ?? "kind";
+    let settle;
+    if (settleIn === "kind") {
+        settle = settleInKind(key, recipient, a);
+    }
+    else {
+        const p = await previewEdit(c, { key, fromId: a.fromId, shares: a.shares, toFloor: a.toFloor, toCap: a.toCap, newL: a.newL });
+        // the swept fees ride INSIDE dQuote (the manager burns by owner and nets them; decisions 018),
+        // so quote's open delta after the update is dQuote itself — `fees` is reported for display only
+        const otherFlow = settleIn === "base" ? p.dQuote : p.dBase; // + = owed, − = released
+        const otherIsBase = settleIn === "quote";
+        if (otherFlow < 0n)
+            actions.push(swapExactInAction({ key, baseIn: otherIsBase, amountIn: OPEN_DELTA }));
+        else if (otherFlow > 0n)
+            actions.push(swapExactOutAction({ key, baseOut: otherIsBase, amountOut: OPEN_DELTA }));
+        settle = settleOnly(key, recipient, settleIn, {
+            maxIn: settleIn === "base" ? a.maxBaseIn : a.maxQuoteIn,
+            minOut: settleIn === "base" ? a.minBaseOut : a.minQuoteOut,
+        });
+    }
+    return execute(c, { actions, settle, deadline: a.deadline, recipient });
+}
+/** The class behind `shares` of `id`: its floor, cap, and the exposure those shares carry. */
+async function classOf(c, key, id, shares) {
+    const [d, cls] = await Promise.all([describeId(c, id, key.tickSpacing), getPositionClass(c, id)]);
+    if (d.poolId === `0x${"0".repeat(64)}`)
+        throw new Error(`logswap: id ${id} was never minted`);
+    const L = cls.shares === 0n ? 0n : (cls.L * shares) / cls.shares;
+    return { floor: d.floor, cap: d.cap, capped: d.capped, L };
+}
+/** Move the floor by `rungs` (signed), cap and L pinned. Positive = harvest, negative = deepen. */
+export async function floor(c, a) {
+    const k = await classOf(c, a.key, a.fromId, a.shares);
+    return edit(c, { ...a, toFloor: k.floor + a.rungs * a.key.tickSpacing, toCap: k.capped ? k.cap : undefined, newL: k.L });
+}
+/**
+ * Raise the floor by `rungs` (default 1) and withdraw PURE QUOTE — the base leg untouched.
+ *
+ * A burn is in kind: it returns base and quote pro rata, so taking α of the proceeds also takes α
+ * of the unsold inventory off the market. Raising the floor instead releases
+ *
+ *   ΔQ = L (ξ' − ξ),   ΔR = 0
+ *
+ * because $R = Le^{-x}$ depends on neither the floor nor the withdrawal. No base moves, the price
+ * does not move, and depth is unchanged. **The cost, which a UI must show:** the position stops
+ * bidding below ξ'. `settleIn: "base"` swaps the proceeds into base in the same batch.
+ */
+export async function harvest(c, a) {
+    const n = a.rungs ?? 1n;
+    if (n <= 0n)
+        throw new Error("logswap: harvest raises the floor — rungs must be positive; to lower it, deepen()");
+    return floor(c, { ...a, rungs: n });
+}
+/**
+ * Lower the floor by `rungs` (default 1), paying L·Δξ of quote for the deeper bid — harvest's
+ * mirror. `settleIn: "base"` pays it in base instead (an exact-out of the quote owed).
+ */
+export async function deepen(c, a) {
+    const n = a.rungs ?? 1n;
+    if (n <= 0n)
+        throw new Error("logswap: deepen lowers the floor — rungs must be positive; to raise it, harvest()");
+    return floor(c, { ...a, rungs: -n });
+}
+/** Move the cap by `rungs` (signed), floor and L pinned. Base flows while the class converts; quote once capped out. */
+export async function cap(c, a) {
+    const k = await classOf(c, a.key, a.fromId, a.shares);
+    if (!k.capped)
+        throw new Error("logswap: cap() needs a capped class — an uncapped one has no cap to move");
+    const toCap = k.cap + a.rungs * a.key.tickSpacing;
+    if (toCap <= k.floor)
+        throw new Error("logswap: the cap cannot sit at or below the floor");
+    return edit(c, { ...a, toFloor: k.floor, toCap, newL: k.L });
+}
+/** Translate the class by `rungs` (signed): floor and cap together, width and L pinned. */
+export async function shift(c, a) {
+    const k = await classOf(c, a.key, a.fromId, a.shares);
+    const d = a.rungs * a.key.tickSpacing;
+    return edit(c, { ...a, toFloor: k.floor + d, toCap: k.capped ? k.cap + d : undefined, newL: k.L });
+}
+/** Set the exposure to `newL`, floor and cap pinned; both legs pro rata. The mint fee bites on an increase only. */
+export async function resize(c, a) {
+    const k = await classOf(c, a.key, a.fromId, a.shares);
+    return edit(c, { ...a, toFloor: k.floor, toCap: k.capped ? k.cap : undefined, newL: a.newL });
+}
+/** Exit `shares` — `resize(0)`. `settleIn: "quote"` (or `"base"`) leaves with one asset. */
+export async function exit(c, a) {
+    const k = await classOf(c, a.key, a.fromId, a.shares);
+    return edit(c, { ...a, toFloor: k.floor, toCap: k.capped ? k.cap : undefined, newL: 0n });
+}
+/**
+ * Re-express a DORMANT class's base at a new trigger price: the base is pinned, so
+ * L' = L·e^{ξ' − ξ} and nothing moves but the trigger. `toFloor` must stay above spot.
+ *
+ * The exponential is evaluated in double precision (~1e-16 relative), which is far inside the
+ * wei-rounding of the class it produces; an exact L' is not what a trigger edit is about.
+ */
+export async function reprice(c, a) {
+    const k = await classOf(c, a.key, a.fromId, a.shares);
+    const ratio = Math.exp(Number(a.toFloor - k.floor) / 1e18);
+    const newL = (k.L * BigInt(Math.round(ratio * 1e18))) / 10n ** 18n;
+    return edit(c, { ...a, toFloor: a.toFloor, toCap: k.capped ? k.cap : undefined, newL });
+}
+/** Quote released by a harvest, exactly: ΔQ = L(ξ' − ξ). Base is untouched. */
+export function harvestProceeds(L, fromFloor, toFloor) {
+    if (toFloor <= fromFloor)
+        return 0n;
+    return (L * (toFloor - fromFloor)) / 10n ** 18n;
+}
+/**
+ * Exit, in kind, across one or more classes. Accrued fees are swept into the same settlement.
+ *
+ * In kind means both legs, pro rata. To take proceeds while leaving inventory in the market, that
+ * is {@link harvest}; to leave with one asset, {@link exit} with `settleIn`.
+ */
+export async function burn(c, a) {
+    if (a.ids.length !== a.shares.length)
+        throw new Error("logswap: ids and shares length mismatch");
+    return sendRouterWrite(c, {
+        abi: logswapRouterAbi,
+        functionName: "burn",
+        args: [
+            a.key,
+            a.ids,
+            a.shares,
+            a.minBaseOut ?? 0n,
+            a.minQuoteOut ?? 0n,
+            resolveRecipient(c, a),
+            resolveDeadline(a),
+        ],
+    });
+}

package/dist/onboard.d.ts

@@ -0,0 +1,56 @@
+/**
+ * onboard.ts — getting a wallet to the point where router writes actually work.
+ *
+ * There are **three separate approvals** with three separate failure modes, and a UI that surfaces
+ * them late produces failed transactions instead of prompts:
+ *
+ *   1. ERC-20 → Permit2      once per token, forever. Only when the router is Permit2-wired.
+ *   2. Permit2 → router      a standing allowance, by transaction or by signature.
+ *   3. 6909 operator grant   once per wallet, covers every market. Needed by burn/update/move.
+ *
+ * **The trap this module exists for:** when the router is deployed with Permit2, approving the
+ * ERC-20 to the *router* is not enough and not used — the pull goes through Permit2, and the
+ * failure is `NotAllowed()` from Permit2 rather than anything naming an allowance. Approving the
+ * router directly looks correct and does nothing.
+ */
+import { type Address, type Hash, type Hex } from "viem";
+import type { LogswapClient } from "./client.js";
+export declare const MAX_UINT256: bigint;
+export declare const MAX_UINT160: bigint;
+export declare const MAX_UINT48: bigint;
+/** Is this deployment's router wired to Permit2? Decides which approval path applies. */
+export declare function usesPermit2(c: LogswapClient): boolean;
+/** The contract that will actually pull tokens: Permit2 when wired, otherwise the router. */
+export declare function spenderFor(c: LogswapClient): Address;
+/** Step 1 — approve the *puller* on an ERC-20. Once per token. */
+export declare function approveToken(c: LogswapClient, token: Address, amount?: bigint): Promise<Hash>;
+/**
+ * Step 2 — the standing Permit2 allowance for the router.
+ *
+ * No-op when the deployment has no Permit2. Prefer the signature flow (`applyPermit2` on the
+ * router, bundled through `multicall`) in production; this transaction form is what a test or a
+ * simple UI wants.
+ */
+export declare function approvePermit2ForRouter(c: LogswapClient, token: Address, amount?: bigint, expiration?: bigint): Promise<Hash | null>;
+/**
+ * Both token-side steps in order, skipping any already satisfied.
+ *
+ * Returns the hashes actually sent, so a UI can report "2 approvals" honestly rather than always
+ * prompting twice.
+ */
+export declare function onboardToken(c: LogswapClient, token: Address, need: bigint): Promise<Hash[]>;
+/** What still stands between this wallet and a working write. */
+export interface TokenReadiness {
+    usesPermit2: boolean;
+    /** ERC-20 allowance to whoever pulls (Permit2 when wired, else the router). */
+    needsTokenApproval: boolean;
+    /** Permit2's standing allowance for the router. Always false when Permit2 is not wired. */
+    needsPermit2Approval: boolean;
+}
+export declare function checkTokenReadiness(c: LogswapClient, token: Address, owner: Address, need: bigint): Promise<TokenReadiness>;
+/**
+ * For each token whose Permit2→router allowance is missing: read the nonce, have the wallet SIGN
+ * a PermitSingle (a signature prompt, not a transaction), and return the encoded `applyPermit2`
+ * calls ready to ride in a router multicall. Tokens already allowed produce nothing.
+ */
+export declare function permit2SigCalls(c: LogswapClient, tokens: Address[]): Promise<Hex[]>;