@logswap/sdk 0.5.35

package/dist/pools.js

@@ -0,0 +1,322 @@
+/**
+ * pools.ts — market state and discovery.
+ *
+ * Two things worth knowing before reading further.
+ *
+ * **Markets are discovered from logs, not configuration.** `Initialize` carries the ENTIRE
+ * `PoolKey` in the clear, so a client can reconstruct any market's key — and therefore call any
+ * keyed function — having never been told the market exists. There is no registry to maintain.
+ *
+ * **`x` is the state, price is derived.** The contract stores $x = \log p$ and materialises the
+ * price only where unavoidable; `priceOf` below mirrors that, and is lossy in the way any float
+ * conversion is. Prefer comparing in log space when precision matters.
+ */
+import { formatUnits } from "viem";
+import { logswapLensAbi, cPoolManagerAbi } from "./generated.js";
+import { readCachedToken, registerCacheClear, writeCachedToken } from "./tokencache.js";
+import { poolId } from "./keys.js";
+/** Read a market's full state by key. */
+export async function getPool(c, key) {
+    const v = await c.public.readContract({
+        address: c.addresses.cPoolManager,
+        abi: cPoolManagerAbi,
+        functionName: "getPool",
+        args: [poolId(key)],
+    });
+    return v;
+}
+/** The effective fee right now: $\max(\phi_{\min}, \kappa\sqrt{\sigma^2_{\text{ema}}})$, capped. */
+export async function phiEff(c, key) {
+    return c.public.readContract({
+        address: c.addresses.cPoolManager,
+        abi: cPoolManagerAbi,
+        functionName: "phiEff",
+        args: [key],
+    });
+}
+/**
+ * Price from the stored log-price. **Lossy** — `x` is exact and this is a float, so use it for
+ * display and never for arithmetic you intend to send back on-chain.
+ */
+export function priceOf(state, scale = 1) {
+    return Math.exp(Number(state.x) / 1e18) * scale;
+}
+/**
+ * The factor between the chain's price and the human one. The chain's log-price is of the WEI
+ * ratio, so with a 6-dec USDC quote and an 18-dec base the human price is `e^x · 10^12`. Pass
+ * this as `scale` to {@link priceOf}, {@link floorPrice} and `fPoolPriceOf` — with 18/18 tokens
+ * it is 1 and nothing changes.
+ */
+export function priceScale(baseDecimals, quoteDecimals) {
+    return 10 ** (baseDecimals - quoteDecimals);
+}
+/**
+ * The model-free LP edge, $F - \tfrac12\Sigma$ — the protocol's headline metric, in quote per unit
+ * of exposure.
+ *
+ * $F$ is fee income per unit active $L$; $\Sigma$ is the realised quadratic variation, whose half
+ * is the LVR a log pool pays. The difference is what an LP actually earns, with no model of the
+ * price process assumed. Both ride on every `Swap` event, so this is reconstructible from logs
+ * alone (docs/app.md) — no state read needed if you are already indexing.
+ *
+ * Signed: negative means variation has outrun fee income over the pool's life.
+ */
+export function lpEdge(state) {
+    return state.F - state.bigSigma / 2n;
+}
+/**
+ * Enumerate markets from `Initialize` logs.
+ *
+ * This is the whole market registry: the event carries every key field rather than just the id,
+ * deliberately, so nothing downstream needs a configured list. Pass `fromBlock` as the manager's
+ * deployment block — scanning from genesis is slow and pointless.
+ */
+export async function discoverMarkets(c, opts = {}) {
+    const ev = cPoolManagerAbi.find((x) => x.type === "event" && x.name === "Initialize");
+    if (!ev)
+        throw new Error("logswap: Initialize event missing from the generated ABI");
+    const logs = await c.public.getLogs({
+        address: c.addresses.cPoolManager,
+        event: ev,
+        args: { base: opts.base, quote: opts.quote },
+        fromBlock: opts.fromBlock ?? 0n,
+        toBlock: opts.toBlock ?? "latest",
+    });
+    return logs.map((l) => {
+        const a = l.args;
+        const key = {
+            base: a.base,
+            quote: a.quote,
+            tickSpacing: a.tickSpacing,
+            phiMin: a.phiMin,
+            kappa: a.kappa,
+            alpha: a.alpha,
+        };
+        return {
+            key,
+            poolId: poolId(key),
+            x0: a.x0,
+            blockNumber: l.blockNumber,
+            transactionHash: l.transactionHash,
+        };
+    });
+}
+/**
+ * Ladder shape: the live FLOORS, in log-price WAD — **not** tick indices.
+ *
+ * Named `liveFloors` deliberately. The lens function it wraps is called `liveTicks`, which reads as
+ * if it returns `k`; it returns `k * tickSpacing`. Multiplying by the spacing again yields an
+ * off-grid value and an `OffGrid` revert at the next call, which is a confusing place to discover
+ * the mistake.
+ */
+export async function liveFloors(c, key) {
+    return c.public.readContract({
+        address: c.addresses.lens,
+        abi: logswapLensAbi,
+        functionName: "liveTicks",
+        args: [key],
+    });
+}
+/** Is this floor on the market's grid, and inside `MAX_ABS_FLOOR`? Pure — no RPC on the manager. */
+export async function isValidFloor(c, key, floor) {
+    return c.public.readContract({
+        address: c.addresses.lens,
+        abi: logswapLensAbi,
+        functionName: "isValidFloor",
+        args: [key, floor],
+    });
+}
+/**
+ * A market's token decimals, read from the tokens themselves.
+ *
+ * **Never assume these.** A market's two tokens routinely differ (USDC 6 against WETH 18), the
+ * manager itself probes `decimals()` to scale `minBackstopL`, and a token that does not implement
+ * it falls back to 18. Hardcoding a guess makes every parse and every display wrong by orders of
+ * magnitude while the contract behaves perfectly — which reads as "the app is broken".
+ */
+export async function marketDecimals(c, key) {
+    const abi = [
+        { type: "function", name: "decimals", stateMutability: "view", inputs: [], outputs: [{ type: "uint8" }] },
+    ];
+    const read = async (token) => {
+        try {
+            return Number(await c.public.readContract({ address: token, abi, functionName: "decimals" }));
+        }
+        catch {
+            return 18; // same fallback the manager uses when the token does not implement it
+        }
+    };
+    const [base, quote] = await Promise.all([read(key.base), read(key.quote)]);
+    return { base, quote };
+}
+/**
+ * Both sides of a market, for labelling and scaling.
+ *
+ * **Decimals are read from the token and never guessed.** They used to fall back to 18 on any
+ * failure, which quietly reintroduced the worst bug this stack has had: an 18 assumed for a
+ * 6-decimal token is a 10^12 error in a number that goes on to `parseUnits` and becomes a transfer
+ * amount. A wrong scale is indistinguishable from a working app until somebody moves funds, so a
+ * read that will not resolve must fail loudly instead.
+ *
+ * `symbol` keeps a fallback because it is a label: a market shown as `0x5FbD…` is ugly, not wrong.
+ *
+ * Retries first, because a blip on the transport is not the same as a token that has no `decimals`,
+ * and killing a market over one dropped packet is its own kind of wrong.
+ *
+ * **Cached** per (chain, address) — see `tokencache.ts` for why only successes are stored and why
+ * the chain id is part of the key. Concurrent calls for the same token share one read, which
+ * matters because the quote asset is usually the same across every market in a deployment.
+ */
+export async function marketTokens(c, key) {
+    const abi = [
+        { type: "function", name: "decimals", stateMutability: "view", inputs: [], outputs: [{ type: "uint8" }] },
+        { type: "function", name: "symbol", stateMutability: "view", inputs: [], outputs: [{ type: "string" }] },
+    ];
+    const chainId = c.public.chain?.id ?? (await c.public.getChainId());
+    const readDecimals = async (address) => {
+        let last;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            try {
+                const d = Number(await c.public.readContract({ address, abi, functionName: "decimals" }));
+                if (!Number.isInteger(d) || d < 0 || d > 36) {
+                    throw new Error(`returned ${d}, which is not a plausible decimals value`);
+                }
+                return d;
+            }
+            catch (e) {
+                last = e;
+                if (attempt < 2)
+                    await new Promise((r) => setTimeout(r, 150 * (attempt + 1)));
+            }
+        }
+        throw new Error(`logswap: could not read decimals() from ${address}. Refusing to assume — every amount for ` +
+            `this token would be scaled wrongly. Cause: ${last instanceof Error ? last.message.split("\n")[0] : String(last)}`);
+    };
+    const read = async (address) => {
+        const hit = readCachedToken(chainId, address);
+        if (hit)
+            return { address, ...hit };
+        const inflight = pending.get(`${chainId}:${address.toLowerCase()}`);
+        if (inflight)
+            return inflight;
+        const k = `${chainId}:${address.toLowerCase()}`;
+        // Deregistration happens INSIDE the job, so it completes before the promise settles. Cleaning
+        // up in a `.finally()` on the outside runs a microtask later — late enough that a caller
+        // arriving right after an `await` could still attach to a job that has already failed and
+        // inherit a failure a fresh read would not have hit. Sharing an in-flight read is an
+        // optimisation for concurrent callers; it must never make a later, separate call fail.
+        // `| undefined` because the assignment below is what tsc cannot see happening first; the
+        // finally only runs after an await, so by then it is set.
+        let self;
+        const job = (async () => {
+            try {
+                // `symbol` is allowed to fail; `decimals` is not. Caught separately so a missing symbol
+                // does not discard a decimals read that succeeded.
+                const [decimals, symbolResult] = await Promise.all([
+                    readDecimals(address),
+                    c.public
+                        .readContract({ address, abi, functionName: "symbol" })
+                        .then((v) => ({ ok: true, value: String(v) }))
+                        .catch(() => ({ ok: false, value: address.slice(0, 6) })),
+                ]);
+                // Only a real symbol is cached. Persisting the 0x… fallback would let one blip name the
+                // token that for as long as the store lives.
+                if (symbolResult.ok)
+                    writeCachedToken(chainId, address, { symbol: symbolResult.value, decimals });
+                return { address, symbol: symbolResult.value, decimals };
+            }
+            finally {
+                if (pending.get(k) === self)
+                    pending.delete(k);
+            }
+        })();
+        self = job;
+        pending.set(k, job);
+        return job;
+    };
+    const [base, quote] = await Promise.all([read(key.base), read(key.quote)]);
+    return { base, quote };
+}
+/** In-flight reads, so simultaneous callers for one token share a single round trip. */
+const pending = new Map();
+registerCacheClear(() => pending.clear());
+/** Format a quote-denominated amount for display, given the quote's decimals. */
+export function formatQuote(amount, quoteDecimals) {
+    return formatUnits(amount, quoteDecimals);
+}
+// ---------------------------------------------------------------------------------------------
+// Denominated readouts
+//
+// `F` and `lpEdge` are per unit of active L — dimensionless WAD fractions, not amounts. A
+// dashboard wants amounts, and multiplying by L is the whole conversion. Keeping these here rather
+// than in the app means one definition of "fees in quote" instead of one per screen.
+// ---------------------------------------------------------------------------------------------
+const WAD = 10n ** 18n;
+const YEAR_SECONDS = 31536000n;
+/** Fees the pool has accrued over its life, in QUOTE units: $F \cdot L$. */
+export function feesQuote(state) {
+    return (state.F * state.lActive) / WAD;
+}
+/** The LP edge in QUOTE units: $(F - \tfrac12\Sigma) \cdot L$. Signed. */
+export function edgeQuote(state) {
+    return (lpEdge(state) * state.lActive) / WAD;
+}
+/** The pool floor as a price. **Lossy** — display only, like {@link priceOf}. */
+export function floorPrice(state, scale = 1) {
+    return Math.exp(Number(state.backstopFloor) / 1e18) * scale;
+}
+/** $\log(p / p_{\text{floor}}) = x - \xi$ — how far spot sits above the floor, in log units (WAD). */
+export function floorDistance(state) {
+    return state.x - state.backstopFloor;
+}
+/**
+ * $-\log(p/p_{\text{floor}})$ as a fraction: the log-drawdown from spot down to the floor.
+ *
+ * **Negative** while price is above the floor — it is how far price has to fall, so a UI can print
+ * it with its sign and mean it. Zero at the floor.
+ *
+ * This is the LOG measure, not the arithmetic one: the actual price drawdown is
+ * $e^{-\Delta} - 1$, which differs materially once the distance is large (a log distance of 0.7
+ * is a 50% price fall, not 70%).
+ */
+export function floorDrawdown(state) {
+    return -Number(floorDistance(state)) / 1e18;
+}
+/** The arithmetic price drawdown to the floor, $p_{\text{floor}}/p - 1$. Negative above the floor. */
+export function floorDrawdownPrice(state) {
+    return Math.exp(-Number(floorDistance(state)) / 1e18) - 1;
+}
+/**
+ * Annualise a per-unit-L WAD rate over the window it accrued in.
+ *
+ * `F` is cumulative fee income per unit of exposure since the pool opened, so dividing by the
+ * elapsed time and scaling to a year gives a rate directly — no price process assumed. Returns a
+ * fraction: 0.12 is 12%.
+ *
+ * Treat it as what it is: a *realised* rate over one short devnet window, not a forecast.
+ */
+export function annualise(perUnitL, elapsedSeconds) {
+    if (elapsedSeconds <= 0n)
+        return 0;
+    return (Number(perUnitL) / 1e18) * (Number(YEAR_SECONDS) / Number(elapsedSeconds));
+}
+/** When a market was created, as a unix timestamp — the denominator for {@link annualise}. */
+export async function marketOpenedAt(c, m) {
+    const b = await c.public.getBlock({ blockNumber: m.blockNumber });
+    return b.timestamp;
+}
+/**
+ * Create a C market: `initialize(key, x0)` on the manager — a call, not a deployment. Manager-
+ * direct by design: creation moves no funds, so the router adds nothing. The pool id is
+ * `poolId(key)` (pure) and the market is tradeable immediately; the first mint funds it.
+ */
+export async function initializeMarket(c, a) {
+    const { request } = await c.public.simulateContract({
+        address: c.addresses.cPoolManager,
+        abi: cPoolManagerAbi,
+        functionName: "initialize",
+        args: [a.key, a.x0],
+        account: a.account,
+    });
+    return c.wallet.writeContract(request);
+}

package/dist/positions.d.ts

@@ -0,0 +1,164 @@
+/**
+ * positions.ts — position and fee reads.
+ *
+ * A position CLASS is fungible at its full key: uncapped by (pool, floor), capped by
+ * (pool, floor, cap). Holders own ERC-6909 shares of a class; fees are tracked per holder, so two
+ * accounts holding the same class can have different claimable amounts.
+ */
+import type { Address } from "viem";
+import type { LogswapClient } from "./client.js";
+import { type PoolKey } from "./keys.js";
+/** A class's aggregate state — the whole class, not one holder's slice. */
+export interface PositionClass {
+    /** Total exposure across every holder. */
+    L: bigint;
+    /** Total shares outstanding. */
+    shares: bigint;
+    /** Fee-per-share accumulator (masterchef-style). */
+    aps: bigint;
+    /** Snapshot of `F_above[floor] − F_above[cap]` at the class's last touch. */
+    insideLast: bigint;
+}
+export declare function getPositionClass(c: LogswapClient, id: bigint): Promise<PositionClass>;
+/** A holder's share balance in a class. */
+export declare function balanceOf(c: LogswapClient, owner: Address, id: bigint): Promise<bigint>;
+/**
+ * A holder's claimable fees, in quote.
+ *
+ * For a capped class this is credit-minus-debit — two accumulator reads, `F_above[floor]` less
+ * `F_above[cap]` — which is monotone non-decreasing, so a capped position can never owe fees.
+ */
+export declare function feesOf(c: LogswapClient, id: bigint, owner: Address): Promise<bigint>;
+/** A holder's full view of one class: what they own and what they can claim. */
+export interface HolderPosition {
+    id: bigint;
+    key: PoolKey;
+    floor: bigint;
+    cap: bigint;
+    capped: boolean;
+    shares: bigint;
+    /** The holder's pro-rata slice of the class's exposure. */
+    L: bigint;
+    claimableFees: bigint;
+}
+/**
+ * Everything a UI needs for one holder in one class. Computes the id offline, so this costs three
+ * reads and no id lookup.
+ */
+export declare function getHolderPosition(c: LogswapClient, key: PoolKey, owner: Address, floor: bigint, cap?: bigint): Promise<HolderPosition>;
+/**
+ * Resolve an id the manager already knows back to its (pool, floor, cap).
+ *
+ * The inverse direction — id to class — needs the registry, because the id is a HASH: it cannot be
+ * unpacked offline the way `positionId` can be computed offline. `IdRegistered` carries the same
+ * information in the clear, so an indexer never needs this call.
+ *
+ * **Units.** The lens is inconsistent here and this wrapper hides it: `unpack` returns tick
+ * INDICES (`kFloor`, `kCap`), while `liveFloors` returns log-price floors. Pass `tickSpacing` and
+ * you get `floor`/`cap` in log-price WAD, the same units `mint` takes; omit it and you get the raw
+ * indices, honestly named.
+ */
+export declare function describeId(c: LogswapClient, id: bigint, tickSpacing?: bigint): Promise<{
+    poolId: `0x${string}`;
+    kFloor: bigint;
+    kCap: bigint;
+    capped: boolean;
+    floor?: bigint;
+    cap?: bigint;
+}>;
+/**
+ * Split ERC-6909 ids into positions and token claims.
+ *
+ * **Do this before treating any `Transfer` as an LP event.** Bit 255 clear means a token claim — a
+ * bearer IOU a market maker uses to park inventory inside the manager — not a position. An indexer
+ * that skips this reports phantom LP positions for every parked balance.
+ */
+export declare function partitionIds(ids: readonly bigint[]): {
+    positions: bigint[];
+    claims: bigint[];
+};
+/** Decode a class's floor and cap from its packed field (as carried by `IdRegistered`). */
+export declare function describePacked(tickSpacing: bigint, packed: bigint): {
+    floor: bigint;
+    cap: bigint;
+    capped: boolean;
+};
+/**
+ * The QUOTE leg of a position at log-price `x`, in quote units.
+ *
+ * Mirrors the manager's `_assets` exactly, in its three cases:
+ *
+ * - **floor above spot** — the position is all base and holds no quote at all.
+ * - **in range** — `L·(x − ξ)`: the buffer built up as price rose from the floor.
+ * - **capped out** (spot at or above the cap) — `L·(cap − ξ)`, frozen. Past its cap a position
+ *   stops converting, which is what makes a capped position a resting limit order.
+ *
+ * Exact: this is bigint arithmetic throughout, unlike the base leg, which needs `L/p` and is
+ * therefore transcendental. If you need base, read it from the chain rather than approximating it
+ * here — a display-only float has no business being subtracted from a balance.
+ */
+export declare function positionQuote(p: {
+    L: bigint;
+    floor: bigint;
+    cap: bigint;
+    capped: boolean;
+}, x: bigint): bigint;
+/** The manager's `MINT_FEE`: 2 bp of newly-earning L, as a WAD fraction. */
+export declare const MINT_FEE: bigint;
+/**
+ * The one-time mint fee at log-price `x`, in quote units — the amount `_mintCore` pulls ON TOP of
+ * the position's own legs, so a mint's total quote pull is `positionQuote(p, x) + mintFee(p, x)`.
+ *
+ * Mirrors the manager's exemption cases: a DORMANT mint pays nothing — floor above spot, or a
+ * capped class spot has already passed (`cap <= x`). Anything earning pays `MINT_FEE · L`, half
+ * accrued through `F` to the LPs already earning, half to the protocol. This is NOT the swap fee:
+ * that one is charged per unit of |Δ log p| on swaps; this is a flat charge on L, once, at mint.
+ *
+ * One rung of imprecision: for a floor or cap exactly AT spot the contract consults its `currentK`
+ * pointer (an up-move counts the tick, a down-move does not), which this offline mirror cannot see.
+ * Preview with it; let the chain be authoritative on that boundary.
+ */
+export declare function mintFee(p: {
+    L: bigint;
+    floor: bigint;
+    cap: bigint;
+    capped: boolean;
+}, x: bigint): bigint;
+/**
+ * Every UNCAPPED position `owner` holds in a market, enumerated fully on-chain by the lens — a
+ * bitmap walk plus a balance check per live floor. No indexer, no log scan. Capped classes are
+ * not listed here by contract (their candidate set is quadratic in live ticks); they come from
+ * `IdRegistered` replay when an indexer exists.
+ */
+export interface HeldPositionRow {
+    id: bigint;
+    floor: bigint;
+    /** NO_CAP for an uncapped class. */
+    cap: bigint;
+    capped: boolean;
+    shares: bigint;
+    /** The holder's slice of the class's exposure. */
+    L: bigint;
+    /** Claimable now, quote units. */
+    fees: bigint;
+}
+export declare function positionsOf(c: LogswapClient, key: PoolKey, owner: Address): Promise<HeldPositionRow[]>;
+/**
+ * EVERY class this owner holds in a pool, capped ones included — the complete book.
+ *
+ * `positionsOf` (the lens) enumerates the uncapped book from the ladder bitmap in one call and
+ * cannot list capped classes: a capped id is a (floor, cap) pair, quadratic in live ticks. This
+ * replays `IdRegistered` — every class is registered once, on first mint, with its floor and
+ * cap — then checks the owner's ERC-6909 balance on each and reads the class for its L, so the
+ * holder's slice is L · shares_owner / shares_class, and fees from the lens. One log query plus
+ * a read per registered class; fine for a pool's lifetime of classes.
+ */
+export declare function holdingsOf(c: LogswapClient, key: PoolKey, owner: Address, fromBlock?: bigint): Promise<HeldPositionRow[]>;
+/** A holding's legs, exact from the lens: base (base units), the quote leg, claimable fees, and
+ *  value = base·p + quote + fees in quote units — L + quote + fees for an uncapped active class. */
+export declare function legsOf(c: LogswapClient, key: PoolKey, id: bigint, holder: Address): Promise<{
+    base: bigint;
+    quote: bigint;
+    fees: bigint;
+    value: bigint;
+}>;

package/dist/positions.js

@@ -0,0 +1,197 @@
+/**
+ * positions.ts — position and fee reads.
+ *
+ * A position CLASS is fungible at its full key: uncapped by (pool, floor), capped by
+ * (pool, floor, cap). Holders own ERC-6909 shares of a class; fees are tracked per holder, so two
+ * accounts holding the same class can have different claimable amounts.
+ */
+import { parseAbiItem } from "viem";
+import { logswapLensAbi, cPoolManagerAbi } from "./generated.js";
+import { poolId } from "./keys.js";
+import { isPosition, NO_CAP, positionId, unpackFloorCap } from "./ids.js";
+export async function getPositionClass(c, id) {
+    const r = (await c.public.readContract({
+        address: c.addresses.cPoolManager,
+        abi: cPoolManagerAbi,
+        functionName: "positions",
+        args: [id],
+    }));
+    return { L: r[0], shares: r[1], aps: r[2], insideLast: r[3] };
+}
+/** A holder's share balance in a class. */
+export async function balanceOf(c, owner, id) {
+    return c.public.readContract({
+        address: c.addresses.cPoolManager,
+        abi: cPoolManagerAbi,
+        functionName: "balanceOf",
+        args: [owner, id],
+    });
+}
+/**
+ * A holder's claimable fees, in quote.
+ *
+ * For a capped class this is credit-minus-debit — two accumulator reads, `F_above[floor]` less
+ * `F_above[cap]` — which is monotone non-decreasing, so a capped position can never owe fees.
+ */
+export async function feesOf(c, id, owner) {
+    return c.public.readContract({
+        address: c.addresses.lens,
+        abi: logswapLensAbi,
+        functionName: "feesOfById",
+        args: [id, owner],
+    });
+}
+/**
+ * Everything a UI needs for one holder in one class. Computes the id offline, so this costs three
+ * reads and no id lookup.
+ */
+export async function getHolderPosition(c, key, owner, floor, cap = NO_CAP) {
+    const id = positionId(poolId(key), key.tickSpacing, floor, cap);
+    const [cls, shares, claimableFees] = await Promise.all([
+        getPositionClass(c, id),
+        balanceOf(c, owner, id),
+        feesOf(c, id, owner),
+    ]);
+    return {
+        id,
+        key,
+        floor,
+        cap,
+        capped: cap !== NO_CAP,
+        shares,
+        L: cls.shares === 0n ? 0n : (cls.L * shares) / cls.shares,
+        claimableFees,
+    };
+}
+/**
+ * Resolve an id the manager already knows back to its (pool, floor, cap).
+ *
+ * The inverse direction — id to class — needs the registry, because the id is a HASH: it cannot be
+ * unpacked offline the way `positionId` can be computed offline. `IdRegistered` carries the same
+ * information in the clear, so an indexer never needs this call.
+ *
+ * **Units.** The lens is inconsistent here and this wrapper hides it: `unpack` returns tick
+ * INDICES (`kFloor`, `kCap`), while `liveFloors` returns log-price floors. Pass `tickSpacing` and
+ * you get `floor`/`cap` in log-price WAD, the same units `mint` takes; omit it and you get the raw
+ * indices, honestly named.
+ */
+export async function describeId(c, id, tickSpacing) {
+    const r = (await c.public.readContract({
+        address: c.addresses.lens,
+        abi: logswapLensAbi,
+        functionName: "unpack",
+        args: [id],
+    }));
+    const out = { poolId: r[0], kFloor: r[1], kCap: r[2], capped: r[3] };
+    if (tickSpacing === undefined)
+        return out;
+    return {
+        ...out,
+        floor: r[1] * tickSpacing,
+        cap: r[3] ? r[2] * tickSpacing : NO_CAP,
+    };
+}
+/**
+ * Split ERC-6909 ids into positions and token claims.
+ *
+ * **Do this before treating any `Transfer` as an LP event.** Bit 255 clear means a token claim — a
+ * bearer IOU a market maker uses to park inventory inside the manager — not a position. An indexer
+ * that skips this reports phantom LP positions for every parked balance.
+ */
+export function partitionIds(ids) {
+    const positions = [];
+    const claims = [];
+    for (const id of ids)
+        (isPosition(id) ? positions : claims).push(id);
+    return { positions, claims };
+}
+/** Decode a class's floor and cap from its packed field (as carried by `IdRegistered`). */
+export function describePacked(tickSpacing, packed) {
+    return unpackFloorCap(tickSpacing, packed);
+}
+/**
+ * The QUOTE leg of a position at log-price `x`, in quote units.
+ *
+ * Mirrors the manager's `_assets` exactly, in its three cases:
+ *
+ * - **floor above spot** — the position is all base and holds no quote at all.
+ * - **in range** — `L·(x − ξ)`: the buffer built up as price rose from the floor.
+ * - **capped out** (spot at or above the cap) — `L·(cap − ξ)`, frozen. Past its cap a position
+ *   stops converting, which is what makes a capped position a resting limit order.
+ *
+ * Exact: this is bigint arithmetic throughout, unlike the base leg, which needs `L/p` and is
+ * therefore transcendental. If you need base, read it from the chain rather than approximating it
+ * here — a display-only float has no business being subtracted from a balance.
+ */
+export function positionQuote(p, x) {
+    if (p.floor > x)
+        return 0n;
+    const upper = p.capped && p.cap <= x ? p.cap : x;
+    return (p.L * (upper - p.floor)) / 10n ** 18n;
+}
+/** The manager's `MINT_FEE`: 2 bp of newly-earning L, as a WAD fraction. */
+export const MINT_FEE = 2n * 10n ** 14n;
+/**
+ * The one-time mint fee at log-price `x`, in quote units — the amount `_mintCore` pulls ON TOP of
+ * the position's own legs, so a mint's total quote pull is `positionQuote(p, x) + mintFee(p, x)`.
+ *
+ * Mirrors the manager's exemption cases: a DORMANT mint pays nothing — floor above spot, or a
+ * capped class spot has already passed (`cap <= x`). Anything earning pays `MINT_FEE · L`, half
+ * accrued through `F` to the LPs already earning, half to the protocol. This is NOT the swap fee:
+ * that one is charged per unit of |Δ log p| on swaps; this is a flat charge on L, once, at mint.
+ *
+ * One rung of imprecision: for a floor or cap exactly AT spot the contract consults its `currentK`
+ * pointer (an up-move counts the tick, a down-move does not), which this offline mirror cannot see.
+ * Preview with it; let the chain be authoritative on that boundary.
+ */
+export function mintFee(p, x) {
+    if (p.floor > x || (p.capped && p.cap <= x))
+        return 0n;
+    return (p.L * MINT_FEE) / 10n ** 18n;
+}
+export async function positionsOf(c, key, owner) {
+    const rows = (await c.public.readContract({
+        address: c.addresses.lens,
+        abi: logswapLensAbi,
+        functionName: "positionsOf",
+        args: [key, owner],
+    }));
+    return rows.map((r) => ({ id: r.id, floor: r.floor, cap: NO_CAP, capped: false, shares: r.shares, L: r.L, fees: r.fees }));
+}
+const ID_REGISTERED = parseAbiItem("event IdRegistered(uint256 indexed id, bytes32 indexed poolId, int256 floor, int256 cap, bool capped)");
+/**
+ * EVERY class this owner holds in a pool, capped ones included — the complete book.
+ *
+ * `positionsOf` (the lens) enumerates the uncapped book from the ladder bitmap in one call and
+ * cannot list capped classes: a capped id is a (floor, cap) pair, quadratic in live ticks. This
+ * replays `IdRegistered` — every class is registered once, on first mint, with its floor and
+ * cap — then checks the owner's ERC-6909 balance on each and reads the class for its L, so the
+ * holder's slice is L · shares_owner / shares_class, and fees from the lens. One log query plus
+ * a read per registered class; fine for a pool's lifetime of classes.
+ */
+export async function holdingsOf(c, key, owner, fromBlock = 0n) {
+    const pool = poolId(key);
+    const logs = await c.public.getLogs({ address: c.addresses.cPoolManager, event: ID_REGISTERED, args: { poolId: pool }, fromBlock, toBlock: "latest" });
+    const ids = logs.map((l) => l.args.id ?? 0n).filter((id) => id !== 0n);
+    if (ids.length === 0)
+        return [];
+    // one lens call: balance, class L, fees, floor and cap for every id the owner holds
+    const rows = (await c.public.readContract({
+        address: c.addresses.lens,
+        abi: logswapLensAbi,
+        functionName: "heldByIds",
+        args: [key, owner, ids],
+    }));
+    return rows.map((r) => ({ id: r.id, floor: r.floor, cap: r.capped ? r.cap : NO_CAP, capped: r.capped, shares: r.shares, L: r.L, fees: r.fees }));
+}
+/** A holding's legs, exact from the lens: base (base units), the quote leg, claimable fees, and
+ *  value = base·p + quote + fees in quote units — L + quote + fees for an uncapped active class. */
+export async function legsOf(c, key, id, holder) {
+    const [base, quote, fees, value] = (await c.public.readContract({
+        address: c.addresses.lens,
+        abi: logswapLensAbi,
+        functionName: "legsOf",
+        args: [key, id, holder],
+    }));
+    return { base, quote, fees, value };
+}