@logswap/sdk 0.5.35

package/src/pools.ts

@@ -0,0 +1,396 @@
+/**
+ * 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, type Address, type Hex } from "viem";
+import { logswapLensAbi, cPoolManagerAbi } from "./generated.js";
+import type { LogswapClient } from "./client.js";
+import { readCachedToken, registerCacheClear, writeCachedToken } from "./tokencache.js";
+import { poolId, type PoolKey } from "./keys.js";
+
+/** The manager's `getPool` view, decoded. Field-for-field with `PoolView` in the contract. */
+export interface PoolState {
+  initialized: boolean;
+  backstopSeeded: boolean;
+  /** $x = \log p$, WAD — the stored state. */
+  x: bigint;
+  /** Exposure currently earning. Steps only when a floor or cap is crossed. */
+  lActive: bigint;
+  reserveBase: bigint;
+  reserveQuote: bigint;
+  /** Fee-per-unit-L accumulator: $\phi \cdot \mathrm{TV}(\log p)$. */
+  F: bigint;
+  /** Quadratic variation of log-price, $\Sigma = \int (dx)^2$. */
+  bigSigma: bigint;
+  sigma2Ema: bigint;
+  currentK: bigint;
+  protocolOwed: bigint;
+  minBackstopL: bigint;
+  backstopFloor: bigint;
+}
+
+/** Read a market's full state by key. */
+export async function getPool(c: LogswapClient, key: PoolKey): Promise<PoolState> {
+  const v = await c.public.readContract({
+    address: c.addresses.cPoolManager,
+    abi: cPoolManagerAbi,
+    functionName: "getPool",
+    args: [poolId(key)],
+  });
+  return v as unknown as PoolState;
+}
+
+/** The effective fee right now: $\max(\phi_{\min}, \kappa\sqrt{\sigma^2_{\text{ema}}})$, capped. */
+export async function phiEff(c: LogswapClient, key: PoolKey): Promise<bigint> {
+  return c.public.readContract({
+    address: c.addresses.cPoolManager,
+    abi: cPoolManagerAbi,
+    functionName: "phiEff",
+    args: [key],
+  }) as Promise<bigint>;
+}
+
+/**
+ * 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: Pick<PoolState, "x">, scale = 1): number {
+  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: number, quoteDecimals: number): number {
+  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: Pick<PoolState, "F" | "bigSigma">): bigint {
+  return state.F - state.bigSigma / 2n;
+}
+
+/** A market discovered from an `Initialize` log — the full key, plus where it was created. */
+export interface DiscoveredMarket {
+  key: PoolKey;
+  poolId: Hex;
+  /** The market's opening log-price. */
+  x0: bigint;
+  blockNumber: bigint;
+  transactionHash: Hex;
+}
+
+/**
+ * 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: LogswapClient,
+  opts: { fromBlock?: bigint; toBlock?: bigint; base?: Address; quote?: Address } = {},
+): Promise<DiscoveredMarket[]> {
+  // Narrow the const ABI to the Initialize entry while KEEPING its literal type, so viem can infer
+  // the log shape. `as never` would compile but collapse every arg to `never` at the call site.
+  type Ev = Extract<(typeof cPoolManagerAbi)[number], { type: "event"; name: "Initialize" }>;
+  const ev = cPoolManagerAbi.find((x): x is Ev => 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: PoolKey = {
+      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: LogswapClient, key: PoolKey): Promise<readonly bigint[]> {
+  return c.public.readContract({
+    address: c.addresses.lens,
+    abi: logswapLensAbi,
+    functionName: "liveTicks",
+    args: [key],
+  }) as Promise<readonly bigint[]>;
+}
+
+/** Is this floor on the market's grid, and inside `MAX_ABS_FLOOR`? Pure — no RPC on the manager. */
+export async function isValidFloor(c: LogswapClient, key: PoolKey, floor: bigint): Promise<boolean> {
+  return c.public.readContract({
+    address: c.addresses.lens,
+    abi: logswapLensAbi,
+    functionName: "isValidFloor",
+    args: [key, floor],
+  }) as Promise<boolean>;
+}
+
+/**
+ * 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: LogswapClient,
+  key: PoolKey,
+): Promise<{ base: number; quote: number }> {
+  const abi = [
+    { type: "function", name: "decimals", stateMutability: "view", inputs: [], outputs: [{ type: "uint8" }] },
+  ] as const;
+  const read = async (token: Address): Promise<number> => {
+    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 };
+}
+
+/** A token as a UI needs it: address, symbol and decimals, all read from the chain. */
+export interface TokenInfo {
+  address: Address;
+  symbol: string;
+  decimals: number;
+}
+
+/**
+ * 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: LogswapClient,
+  key: PoolKey,
+): Promise<{ base: TokenInfo; quote: TokenInfo }> {
+  const abi = [
+    { type: "function", name: "decimals", stateMutability: "view", inputs: [], outputs: [{ type: "uint8" }] },
+    { type: "function", name: "symbol", stateMutability: "view", inputs: [], outputs: [{ type: "string" }] },
+  ] as const;
+
+  const chainId = c.public.chain?.id ?? (await c.public.getChainId());
+
+  const readDecimals = async (address: Address): Promise<number> => {
+    let last: unknown;
+    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: Address): Promise<TokenInfo> => {
+    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: Promise<TokenInfo> | undefined;
+    const job = (async (): Promise<TokenInfo> => {
+      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 as const, value: String(v) }))
+            .catch(() => ({ ok: false as const, 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<string, Promise<TokenInfo>>();
+registerCacheClear(() => pending.clear());
+
+/** Format a quote-denominated amount for display, given the quote's decimals. */
+export function formatQuote(amount: bigint, quoteDecimals: number): string {
+  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 = 31_536_000n;
+
+/** Fees the pool has accrued over its life, in QUOTE units: $F \cdot L$. */
+export function feesQuote(state: Pick<PoolState, "F" | "lActive">): bigint {
+  return (state.F * state.lActive) / WAD;
+}
+
+/** The LP edge in QUOTE units: $(F - \tfrac12\Sigma) \cdot L$. Signed. */
+export function edgeQuote(state: Pick<PoolState, "F" | "bigSigma" | "lActive">): bigint {
+  return (lpEdge(state) * state.lActive) / WAD;
+}
+
+/** The pool floor as a price. **Lossy** — display only, like {@link priceOf}. */
+export function floorPrice(state: Pick<PoolState, "backstopFloor">, scale = 1): number {
+  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: Pick<PoolState, "x" | "backstopFloor">): bigint {
+  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: Pick<PoolState, "x" | "backstopFloor">): number {
+  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: Pick<PoolState, "x" | "backstopFloor">): number {
+  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: bigint, elapsedSeconds: bigint): number {
+  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: LogswapClient, m: DiscoveredMarket): Promise<bigint> {
+  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: LogswapClient, a: { key: PoolKey; x0: bigint; account: Address }) {
+  const { request } = await c.public.simulateContract({
+    address: c.addresses.cPoolManager,
+    abi: cPoolManagerAbi,
+    functionName: "initialize",
+    args: [a.key, a.x0],
+    account: a.account,
+  } as never);
+  return c.wallet!.writeContract(request as never);
+}

package/src/positions.ts

@@ -0,0 +1,276 @@
+/**
+ * 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 type { Address } from "viem";
+import { logswapLensAbi, cPoolManagerAbi } from "./generated.js";
+import type { LogswapClient } from "./client.js";
+import { poolId, type PoolKey } from "./keys.js";
+import { isPosition, NO_CAP, positionId, unpackFloorCap } from "./ids.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 async function getPositionClass(c: LogswapClient, id: bigint): Promise<PositionClass> {
+  const r = (await c.public.readContract({
+    address: c.addresses.cPoolManager,
+    abi: cPoolManagerAbi,
+    functionName: "positions",
+    args: [id],
+  })) as readonly [bigint, bigint, bigint, bigint];
+  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: LogswapClient, owner: Address, id: bigint): Promise<bigint> {
+  return c.public.readContract({
+    address: c.addresses.cPoolManager,
+    abi: cPoolManagerAbi,
+    functionName: "balanceOf",
+    args: [owner, id],
+  }) as 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 async function feesOf(c: LogswapClient, id: bigint, owner: Address): Promise<bigint> {
+  return c.public.readContract({
+    address: c.addresses.lens,
+    abi: logswapLensAbi,
+    functionName: "feesOfById",
+    args: [id, owner],
+  }) as 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 async function getHolderPosition(
+  c: LogswapClient,
+  key: PoolKey,
+  owner: Address,
+  floor: bigint,
+  cap: bigint = NO_CAP,
+): Promise<HolderPosition> {
+  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: LogswapClient,
+  id: bigint,
+  tickSpacing?: bigint,
+): Promise<{
+  poolId: `0x${string}`;
+  kFloor: bigint;
+  kCap: bigint;
+  capped: boolean;
+  floor?: bigint;
+  cap?: bigint;
+}> {
+  const r = (await c.public.readContract({
+    address: c.addresses.lens,
+    abi: logswapLensAbi,
+    functionName: "unpack",
+    args: [id],
+  })) as readonly [`0x${string}`, bigint, bigint, boolean];
+  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: readonly bigint[]): { positions: bigint[]; claims: bigint[] } {
+  const positions: bigint[] = [];
+  const claims: bigint[] = [];
+  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: bigint, packed: bigint) {
+  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: { L: bigint; floor: bigint; cap: bigint; capped: boolean },
+  x: bigint,
+): bigint {
+  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: { L: bigint; floor: bigint; cap: bigint; capped: boolean },
+  x: bigint,
+): bigint {
+  if (p.floor > x || (p.capped && p.cap <= x)) return 0n;
+  return (p.L * MINT_FEE) / 10n ** 18n;
+}
+
+/**
+ * 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 async function positionsOf(c: LogswapClient, key: PoolKey, owner: Address): Promise<HeldPositionRow[]> {
+  const rows = (await c.public.readContract({
+    address: c.addresses.lens,
+    abi: logswapLensAbi,
+    functionName: "positionsOf",
+    args: [key, owner],
+  } as never)) as readonly { id: bigint; floor: bigint; shares: bigint; L: bigint; fees: bigint }[];
+  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: LogswapClient, key: PoolKey, owner: Address, fromBlock: bigint = 0n): Promise<HeldPositionRow[]> {
+  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 as { id?: bigint }).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],
+  } as never)) as readonly { id: bigint; floor: bigint; cap: bigint; capped: boolean; shares: bigint; L: bigint; fees: bigint }[];
+  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: LogswapClient, key: PoolKey, id: bigint, holder: Address): Promise<{ base: bigint; quote: bigint; fees: bigint; value: bigint }> {
+  const [base, quote, fees, value] = (await c.public.readContract({
+    address: c.addresses.lens,
+    abi: logswapLensAbi,
+    functionName: "legsOf",
+    args: [key, id, holder],
+  } as never)) as readonly [bigint, bigint, bigint, bigint];
+  return { base, quote, fees, value };
+}