@logswap/sdk 0.5.35

package/README.md

@@ -0,0 +1,130 @@
+# logswap-sdk
+
+TypeScript SDK for [Logswap](https://github.com/logswap/logswap-contract), the liquidity
+primitive introducing the **logarithmic invariant** — typed wrappers over the `CPoolManager` /
+`FPoolManager` / `LogswapRouter` / `LogswapLens` surface.
+
+**Status: identity, reads and writes for both singletons.** Indexer next.
+
+## What is here now
+
+The two things the SDK must own because they are easy to get wrong by hand, and because getting them
+wrong is silent:
+
+| module | what it does |
+|---|---|
+| `src/keys.ts` | `PoolKey` and `poolId = keccak256(abi.encode(key))` — market identity |
+| `src/ids.ts` | the ERC-6909 id namespace: position-class ids, token-claim ids, floor/cap packing |
+| `src/client.ts` | the handle, plus `assertVersion` — refuse a deployment the ABI was not built for |
+| `src/pools.ts` | market discovery from `Initialize` logs, pool state, `lpEdge` = F − Σ/2 |
+| `src/positions.ts` | classes, balances, claimable fees, the bit-255 position/claim split |
+| `src/swap.ts` | exact-in/out, multi-hop, and exact quotes via the revert-quoter |
+| `src/liquidity.ts` | mint, blended mint, zap, update, move, **harvest**, burn |
+| `src/claims.ts` | fee claims and the 6909 operator grant |
+| `src/onboard.ts` | the three approvals — ERC-20 → Permit2 → router, and the 6909 grant |
+
+Both are computed **offline** — no RPC, no deployment needed to address a market or a position.
+
+## Reading a holder's book
+
+- `positionsOf(c, key, owner)` — the **uncapped** book in one lens call (the ladder bitmap
+  enumerates floors; an uncapped id is a pure function of the floor).
+- `holdingsOf(c, key, owner)` — the **complete** book, capped classes included: replays
+  `IdRegistered` (every class is registered once, with its floor and cap) and checks the owner's
+  balance on each. Use this for "my positions"; a capped mint is invisible to `positionsOf`.
+- `getHolderPosition(c, key, owner, floor, cap?)` — one class by (floor, cap); `move(...)` /
+  `update(...)` / `harvest(...)` / `burn(...)` / `claimFees(...)` act on it.
+- F side: `discoverFPools(c)` (shape, and the `block` the pool was initialized in), `getFPool`,
+  `fPoolShareBalance`, `fPoolShareValue`; `previewZapIn` reads the **lens** (the router's F flows
+  live in a facet, its previews moved to the lens).
+
+## The derivation gate
+
+Both derivations are **tier-1 frozen** (`docs/app.md`): `poolId` is the primary key of the entire
+read model, and the position id is `(1 << 255) | (keccak256(poolId ‖ packed) >> 1)`, baked into every
+client. If the TypeScript and the Solidity disagree, a client addresses the wrong pool or the wrong
+position — silently, with funds behind it.
+
+So `test/derivation.test.ts` checks against **vectors generated by the contract**, not by hand:
+
+```bash
+npm run vectors   # regenerate from the pinned contracts
+npm test          # 45 vectors × poolId, positionId, pack/unpack round-trip
+```
+
+That makes it a genuine cross-implementation check. It is also verified non-vacuous: changing the
+id derivation's shift by one bit fails all 45 position-id vectors.
+
+A diff in `vectors/derivation-vectors.json` during an ordinary change means something is wrong — by
+definition, a change there is a tier-1 event.
+
+## The pipeline
+
+```
+logswap (forge)  ──►  contracts/abi/*.json  ──►  wagmi codegen  ──►  src/generated.ts
+      ▲                                                                     │
+  contracts.ref (pinned SHA)                                        the SDK wrappers
+```
+
+Nothing is ever hand-copied. `contracts.ref` pins the SHA; `npm run codegen` clones it, builds, and
+regenerates; `tsc` is the drift gate, so a contract change that breaks the SDK is a red build rather
+than a runtime surprise.
+
+```bash
+npm run codegen     # sync the pinned contracts, forge build, wagmi generate -> src/generated.ts
+npm run typecheck   # consumes generated.ts; run codegen first on a fresh checkout
+npm run build
+npm test
+```
+
+`typecheck` and `build` both *consume* `src/generated.ts` and neither produces it, so codegen
+runs once and explicitly rather than being chained into both.
+
+## Conventions
+
+- **The SDK hides the manager/router/lens split.** Which contract hosts which action is currently
+  decided by EIP-170 headroom, not by design — so a future re-homing must be an SDK patch, not a
+  breaking change for consumers.
+- **Zero is not the default.** `phiMin` and `alpha` of `0n` resolve to their defaults at *read* time,
+  so a key carrying `0n` and one carrying the resolved value are **different markets with different
+  ids**. Always address a market by the key it was initialized with.
+- **Split every ERC-6909 `Transfer` on bit 255.** Clear means a token claim, not a position; an
+  indexer that ignores this reports phantom LP positions for market makers parking inventory.
+
+## Install
+
+```bash
+npm i @logswap/sdk viem
+```
+
+Published as **`@logswap/sdk`** from v0.5.35. Everything up to v0.5.34 was
+`@unimodular/logswap-sdk`, which is deprecated and points here — the code is identical, only the
+name moved, along with the repos to the `logswap` org.
+
+`viem` is a peer dependency. The package ships `dist/` plus `src/`, including the generated ABIs, so
+the contract surface it was built against travels with it.
+
+## Release
+
+Push-driven, and there is **no npm token anywhere**: publishing uses OIDC trusted publishing, so npm
+verifies a GitHub-issued token per run and there is no long-lived credential to rotate or leak.
+
+```
+logswap-contract push
+   → Update SDK contracts pin   (GitHub App token, cross-repo)
+   → commit contracts.ref here
+   → Release on contracts pin change
+   → codegen at the pinned SHA → build → test → version bump → npm publish --provenance
+```
+
+`workflow_dispatch` covers SDK-only fixes with no contracts change: same pipeline, manual trigger.
+The version bump touches `package.json` only, not `contracts.ref`, so it cannot re-trigger itself.
+
+Two things that are easy to get wrong:
+
+- **`codegen` must run before `typecheck`.** `src/generated.ts` is gitignored, so it exists on a
+  developer machine and never in CI — a `typecheck`-first pipeline fails only in CI, which is where
+  it is least convenient to debug.
+- **`0.1.0` has no provenance attestation, every release after does.** Trusted publishing cannot be
+  configured for a package that does not exist yet, so the first publish is necessarily manual.
+  `prepublishOnly` runs the build, so a hand-run publish cannot ship a stale `dist/`.

package/dist/actions.d.ts

@@ -0,0 +1,136 @@
+/**
+ * actions.ts — the router's transaction: a BATCH (decisions 010).
+ *
+ * `execute(actions, settle)` runs a list of actions — mint, burn, update, claim, swap, path, in any
+ * order, across any C markets — under ONE manager lock. Each action accrues deltas on the router
+ * and settles nothing; the batch settles once per token in `settle.tokens`, pulling at most
+ * `maxIn[i]` from the caller and taking at least `minOut[i]` to the recipient. A touched token
+ * left off the list fails the manager's own close (`TokensNotSettled`), so the list is also the
+ * caller's statement of which tokens may move.
+ *
+ * `OPEN_DELTA` as a swap amount means "the router's open delta of that token": what earlier
+ * actions left it holding (exact-in, path) or owing (exact-out). It is what lets action i+1
+ * consume action i's proceeds — a harvest funds a buy, a burn exits to one asset, a deepen is paid
+ * in base — each moving ONE token.
+ *
+ * Payloads are `abi.encode` of the router's `*Act` structs. Their tuple types are read from the
+ * generated ABI (the router's pure `encode*` helpers exist for exactly this), so nothing here is
+ * hand-written and a struct change is a `tsc`/vector failure, not a runtime surprise.
+ */
+import { type Address, type Hash, type Hex } from "viem";
+import type { LogswapClient } from "./client.js";
+import type { PoolKey } from "./keys.js";
+import type { Hop } from "./swap.js";
+import { type WriteOptions } from "./write.js";
+/** "The router's open delta of that token" — the swap-amount sentinel. `type(uint256).max`. */
+export declare const OPEN_DELTA: bigint;
+/** No bound. The same word as the sentinel, kept apart because it means something else. */
+export declare const UNBOUNDED: bigint;
+/** The router's op tags — `OpType` in `RouterOps.sol`, C actions only (the F ops have their own lock). */
+export declare enum Op {
+    MintBlended = 0,
+    Burn = 1,
+    SwapExactIn = 2,
+    SwapExactOut = 3,
+    Claim = 4,
+    Update = 5,
+    Path = 6
+}
+export interface Action {
+    op: Op;
+    data: Hex;
+}
+export interface Settle {
+    tokens: readonly Address[];
+    maxIn: readonly bigint[];
+    minOut: readonly bigint[];
+    /** Receives whatever is taken, and the shares the actions mint. */
+    recipient: Address;
+}
+/** Mint exposure `L` at `targetFloor` (off-grid blends the two adjacent rungs), `cap` optional. */
+export declare function mintAction(a: {
+    key: PoolKey;
+    targetFloor: bigint;
+    cap?: bigint;
+    L: bigint;
+}): Action;
+/** Burn `shares[i]` of `ids[i]`; accrued fees are swept into the same batch. Needs the operator grant. */
+export declare function burnAction(a: {
+    key: PoolKey;
+    ids: readonly bigint[];
+    shares: readonly bigint[];
+}): Action;
+/** Exact-in swap. `amountIn` may be `OPEN_DELTA`: the input an earlier action left the router holding. */
+export declare function swapExactInAction(a: {
+    key: PoolKey;
+    baseIn: boolean;
+    amountIn: bigint;
+    minOut?: bigint;
+}): Action;
+/** Exact-out swap. `amountOut` may be `OPEN_DELTA`: the output an earlier action left the router owing. */
+export declare function swapExactOutAction(a: {
+    key: PoolKey;
+    baseOut: boolean;
+    amountOut: bigint;
+    maxIn?: bigint;
+}): Action;
+/** Collect the caller's fees on `ids`; positions untouched. */
+export declare function claimAction(a: {
+    key: PoolKey;
+    ids: readonly bigint[];
+}): Action;
+/** The general edit — set `shares` of `fromId` to (`toFloor`, `toCap`, `newL`); `newL = 0` exits. */
+export declare function updateAction(a: {
+    key: PoolKey;
+    fromId: bigint;
+    shares: bigint;
+    toFloor: bigint;
+    toCap?: bigint;
+    newL: bigint;
+}): Action;
+/** Multi-hop exact-in route; `amountIn` may be `OPEN_DELTA`. Intermediate tokens never move. */
+export declare function pathAction(a: {
+    hops: readonly Hop[];
+    amountIn: bigint;
+    minOut?: bigint;
+}): Action;
+/** A settlement over explicit tokens; missing bounds default to unbounded in, zero out. */
+export declare function settlement(a: {
+    tokens: readonly Address[];
+    maxIn?: readonly bigint[];
+    minOut?: readonly bigint[];
+    recipient: Address;
+}): Settle;
+export interface PairBounds {
+    maxBaseIn?: bigint;
+    maxQuoteIn?: bigint;
+    minBaseOut?: bigint;
+    minQuoteOut?: bigint;
+}
+/** Settle both of a market's tokens, in kind. */
+export declare function settleInKind(key: PoolKey, recipient: Address, b?: PairBounds): Settle;
+/**
+ * Settle in ONE of a market's tokens: the other is bound to zero both ways, so the batch must have
+ * netted it — which is what a trailing `OPEN_DELTA` swap does.
+ */
+export declare function settleOnly(key: PoolKey, recipient: Address, side: "base" | "quote", b?: {
+    maxIn?: bigint;
+    minOut?: bigint;
+}): Settle;
+export interface ExecuteArgs extends WriteOptions {
+    actions: readonly Action[];
+    settle: Omit<Settle, "recipient"> & {
+        recipient?: Address;
+    };
+    /** Tokens the batch may pull, for the Permit2 signatures. Defaults to every token with `maxIn > 0`. */
+    pullTokens?: readonly Address[];
+}
+/** Run a batch: one lock, one settlement per token, one transaction (Permit2 signatures ride inside). */
+export declare function execute(c: LogswapClient, a: ExecuteArgs): Promise<Hash>;
+/** Simulate a batch: the per-action returns and the signed flows (+ = paid in), without sending. */
+export declare function simulateExecute(c: LogswapClient, a: ExecuteArgs & {
+    account?: Address;
+}): Promise<{
+    results: readonly Hex[];
+    flows: readonly bigint[];
+}>;

package/dist/actions.js

@@ -0,0 +1,140 @@
+/**
+ * actions.ts — the router's transaction: a BATCH (decisions 010).
+ *
+ * `execute(actions, settle)` runs a list of actions — mint, burn, update, claim, swap, path, in any
+ * order, across any C markets — under ONE manager lock. Each action accrues deltas on the router
+ * and settles nothing; the batch settles once per token in `settle.tokens`, pulling at most
+ * `maxIn[i]` from the caller and taking at least `minOut[i]` to the recipient. A touched token
+ * left off the list fails the manager's own close (`TokensNotSettled`), so the list is also the
+ * caller's statement of which tokens may move.
+ *
+ * `OPEN_DELTA` as a swap amount means "the router's open delta of that token": what earlier
+ * actions left it holding (exact-in, path) or owing (exact-out). It is what lets action i+1
+ * consume action i's proceeds — a harvest funds a buy, a burn exits to one asset, a deepen is paid
+ * in base — each moving ONE token.
+ *
+ * Payloads are `abi.encode` of the router's `*Act` structs. Their tuple types are read from the
+ * generated ABI (the router's pure `encode*` helpers exist for exactly this), so nothing here is
+ * hand-written and a struct change is a `tsc`/vector failure, not a runtime surprise.
+ */
+import { encodeAbiParameters } from "viem";
+import { logswapRouterAbi } from "./generated.js";
+import { NO_CAP } from "./ids.js";
+import { resolveDeadline, resolveRecipient, sendRouterWriteWithPermits, simulateRouterWrite } from "./write.js";
+/** "The router's open delta of that token" — the swap-amount sentinel. `type(uint256).max`. */
+export const OPEN_DELTA = (1n << 256n) - 1n;
+/** No bound. The same word as the sentinel, kept apart because it means something else. */
+export const UNBOUNDED = (1n << 256n) - 1n;
+/** The router's op tags — `OpType` in `RouterOps.sol`, C actions only (the F ops have their own lock). */
+export var Op;
+(function (Op) {
+    Op[Op["MintBlended"] = 0] = "MintBlended";
+    Op[Op["Burn"] = 1] = "Burn";
+    Op[Op["SwapExactIn"] = 2] = "SwapExactIn";
+    Op[Op["SwapExactOut"] = 3] = "SwapExactOut";
+    Op[Op["Claim"] = 4] = "Claim";
+    Op[Op["Update"] = 5] = "Update";
+    Op[Op["Path"] = 6] = "Path";
+})(Op || (Op = {}));
+/* payload encoding ========================================================== */
+function payloadType(encoder) {
+    const f = logswapRouterAbi.find((x) => x.type === "function" && x.name === encoder);
+    if (!f?.inputs)
+        throw new Error(`logswap: the router ABI has no ${encoder} — SDK and contracts disagree`);
+    return f.inputs;
+}
+const enc = (encoder, value) => encodeAbiParameters(payloadType(encoder), [value]);
+/** Mint exposure `L` at `targetFloor` (off-grid blends the two adjacent rungs), `cap` optional. */
+export function mintAction(a) {
+    return { op: Op.MintBlended, data: enc("encodeMint", { key: a.key, targetFloor: a.targetFloor, cap: a.cap ?? NO_CAP, L: a.L }) };
+}
+/** Burn `shares[i]` of `ids[i]`; accrued fees are swept into the same batch. Needs the operator grant. */
+export function burnAction(a) {
+    if (a.ids.length !== a.shares.length)
+        throw new Error("logswap: ids and shares length mismatch");
+    return { op: Op.Burn, data: enc("encodeBurn", { key: a.key, ids: a.ids, shares: a.shares }) };
+}
+/** Exact-in swap. `amountIn` may be `OPEN_DELTA`: the input an earlier action left the router holding. */
+export function swapExactInAction(a) {
+    return { op: Op.SwapExactIn, data: enc("encodeSwap", { key: a.key, baseSide: a.baseIn, amount: a.amountIn, limit: a.minOut ?? 0n }) };
+}
+/** Exact-out swap. `amountOut` may be `OPEN_DELTA`: the output an earlier action left the router owing. */
+export function swapExactOutAction(a) {
+    return {
+        op: Op.SwapExactOut,
+        data: enc("encodeSwap", { key: a.key, baseSide: a.baseOut, amount: a.amountOut, limit: a.maxIn ?? UNBOUNDED }),
+    };
+}
+/** Collect the caller's fees on `ids`; positions untouched. */
+export function claimAction(a) {
+    return { op: Op.Claim, data: enc("encodeClaim", { key: a.key, ids: a.ids }) };
+}
+/** The general edit — set `shares` of `fromId` to (`toFloor`, `toCap`, `newL`); `newL = 0` exits. */
+export function updateAction(a) {
+    return {
+        op: Op.Update,
+        data: enc("encodeUpdate", {
+            key: a.key,
+            fromId: a.fromId,
+            shares: a.shares,
+            toFloor: a.toFloor,
+            toCap: a.toCap ?? NO_CAP,
+            newL: a.newL,
+        }),
+    };
+}
+/** Multi-hop exact-in route; `amountIn` may be `OPEN_DELTA`. Intermediate tokens never move. */
+export function pathAction(a) {
+    if (a.hops.length === 0)
+        throw new Error("logswap: empty path");
+    return { op: Op.Path, data: enc("encodePath", { hops: a.hops, amountIn: a.amountIn, minOut: a.minOut ?? 0n }) };
+}
+/* settlement builders ======================================================= */
+/** A settlement over explicit tokens; missing bounds default to unbounded in, zero out. */
+export function settlement(a) {
+    const n = a.tokens.length;
+    const maxIn = a.maxIn ?? a.tokens.map(() => UNBOUNDED);
+    const minOut = a.minOut ?? a.tokens.map(() => 0n);
+    if (maxIn.length !== n || minOut.length !== n)
+        throw new Error("logswap: settlement bounds length mismatch");
+    return { tokens: a.tokens, maxIn, minOut, recipient: a.recipient };
+}
+/** Settle both of a market's tokens, in kind. */
+export function settleInKind(key, recipient, b = {}) {
+    return settlement({
+        tokens: [key.base, key.quote],
+        maxIn: [b.maxBaseIn ?? UNBOUNDED, b.maxQuoteIn ?? UNBOUNDED],
+        minOut: [b.minBaseOut ?? 0n, b.minQuoteOut ?? 0n],
+        recipient,
+    });
+}
+/**
+ * Settle in ONE of a market's tokens: the other is bound to zero both ways, so the batch must have
+ * netted it — which is what a trailing `OPEN_DELTA` swap does.
+ */
+export function settleOnly(key, recipient, side, b = {}) {
+    const base = side === "base";
+    return settlement({
+        tokens: [key.base, key.quote],
+        maxIn: [base ? (b.maxIn ?? UNBOUNDED) : 0n, base ? 0n : (b.maxIn ?? UNBOUNDED)],
+        minOut: [base ? (b.minOut ?? 0n) : 0n, base ? 0n : (b.minOut ?? 0n)],
+        recipient,
+    });
+}
+/** Run a batch: one lock, one settlement per token, one transaction (Permit2 signatures ride inside). */
+export async function execute(c, a) {
+    const settle = { ...a.settle, recipient: a.settle.recipient ?? resolveRecipient(c, a) };
+    const pull = a.pullTokens ?? settle.tokens.filter((_, i) => settle.maxIn[i] > 0n);
+    return sendRouterWriteWithPermits(c, { abi: logswapRouterAbi, functionName: "execute", args: [a.actions, settle, resolveDeadline(a)] }, [...pull]);
+}
+/** Simulate a batch: the per-action returns and the signed flows (+ = paid in), without sending. */
+export async function simulateExecute(c, a) {
+    const settle = { ...a.settle, recipient: a.settle.recipient ?? a.account ?? resolveRecipient(c, a) };
+    const [results, flows] = await simulateRouterWrite(c, {
+        abi: logswapRouterAbi,
+        functionName: "execute",
+        args: [a.actions, settle, resolveDeadline(a)],
+        account: a.account,
+    });
+    return { results, flows };
+}

package/dist/admin.d.ts

@@ -0,0 +1,11 @@
+/**
+ * admin — the protocol's (feeCollector's) writes: the fee rates, the harvest-fee exemption, and
+ * the two-step collector handover, on both managers. Plain writes to the managers; no router.
+ */
+import type { Address, Hash, Hex } from "viem";
+import type { LogswapClient } from "./client.js";
+export declare function setProtocolFeeCut(c: LogswapClient, cutWad: bigint): Promise<Hash>;
+export declare function setFeeParams(c: LogswapClient, mintFeeProtocolCutWad: bigint, harvestFeeWad: bigint): Promise<Hash>;
+export declare function setHarvestFeeExempt(c: LogswapClient, poolId: Hex, exempt: boolean): Promise<Hash>;
+export declare function proposeCollector(c: LogswapClient, side: "C" | "F", next: Address): Promise<Hash>;
+export declare function acceptCollector(c: LogswapClient, side: "C" | "F"): Promise<Hash>;

package/dist/admin.js

@@ -0,0 +1,29 @@
+/**
+ * admin — the protocol's (feeCollector's) writes: the fee rates, the harvest-fee exemption, and
+ * the two-step collector handover, on both managers. Plain writes to the managers; no router.
+ */
+import { cPoolManagerAbi, fPoolManagerAbi } from "./generated.js";
+function wallet(c) {
+    if (!c.wallet)
+        throw new Error("a wallet client is required");
+    return c.wallet;
+}
+export async function setProtocolFeeCut(c, cutWad) {
+    return wallet(c).writeContract({ address: c.addresses.cPoolManager, abi: cPoolManagerAbi, functionName: "setProtocolFeeCut", args: [cutWad], chain: c.wallet.chain, account: c.wallet.account });
+}
+export async function setFeeParams(c, mintFeeProtocolCutWad, harvestFeeWad) {
+    return wallet(c).writeContract({ address: c.addresses.fPoolManager, abi: fPoolManagerAbi, functionName: "setFeeParams", args: [mintFeeProtocolCutWad, harvestFeeWad], chain: c.wallet.chain, account: c.wallet.account });
+}
+export async function setHarvestFeeExempt(c, poolId, exempt) {
+    return wallet(c).writeContract({ address: c.addresses.fPoolManager, abi: fPoolManagerAbi, functionName: "setHarvestFeeExempt", args: [poolId, exempt], chain: c.wallet.chain, account: c.wallet.account });
+}
+export async function proposeCollector(c, side, next) {
+    const address = side === "C" ? c.addresses.cPoolManager : c.addresses.fPoolManager;
+    const abi = side === "C" ? cPoolManagerAbi : fPoolManagerAbi;
+    return wallet(c).writeContract({ address, abi, functionName: "proposeCollector", args: [next], chain: c.wallet.chain, account: c.wallet.account });
+}
+export async function acceptCollector(c, side) {
+    const address = side === "C" ? c.addresses.cPoolManager : c.addresses.fPoolManager;
+    const abi = side === "C" ? cPoolManagerAbi : fPoolManagerAbi;
+    return wallet(c).writeContract({ address, abi, functionName: "acceptCollector", args: [], chain: c.wallet.chain, account: c.wallet.account });
+}

package/dist/claims.d.ts

@@ -0,0 +1,53 @@
+/**
+ * claims.ts — fee claims, and the ERC-6909 operator grant every router write depends on.
+ *
+ * Note the two unrelated meanings of "claim" in this protocol, kept apart here:
+ *   - a FEE claim   — `claimFees`, withdrawing accrued quote while the position stays whole
+ *   - a TOKEN claim — a bearer IOU (bit-255-clear id) for inventory parked inside the manager
+ */
+import type { Address, Hash } from "viem";
+import type { LogswapClient } from "./client.js";
+import type { PoolKey } from "./keys.js";
+import { type WriteOptions } from "./write.js";
+export interface ClaimFeesArgs extends WriteOptions {
+    key: PoolKey;
+    ids: readonly bigint[];
+}
+/**
+ * Claim accrued fees across one or more classes: one transfer, positions untouched.
+ *
+ * **Every id must be REGISTERED** — one the manager has seen minted. An id for a class that has
+ * never existed reverts the whole batch with `WrongPool`, because an unregistered id has
+ * `poolId == 0` and cannot be shown to belong to this pool. In a contract holding every market's
+ * assets, "cannot be shown to belong" must not be read as "belongs". A class that exists but which
+ * the caller does not hold is fine — that is a no-op, not a revert.
+ */
+export declare function claimFees(c: LogswapClient, a: ClaimFeesArgs): Promise<Hash>;
+/**
+ * Grant the router operator rights over your ERC-6909 positions.
+ *
+ * **Required before any burn, update, move or harvest** — those pull the shares to the router
+ * first. Without it they revert on the transfer, which reads as an unrelated balance error. Swaps
+ * and mints do not need it.
+ *
+ * One grant covers every market, because the positions all live in the one manager.
+ */
+export declare function approveRouterAsOperator(c: LogswapClient, approved?: boolean): Promise<Hash>;
+/** Is the router already an operator for `owner`? Check before prompting for a signature. */
+export declare function isRouterApproved(c: LogswapClient, owner: Address): Promise<boolean>;
+/**
+ * What a wallet still has to approve before a given action.
+ *
+ * Surfacing this up front is the difference between one prompt and a failed transaction: the ERC-20
+ * allowances and the 6909 operator grant are separate approvals with separate failure modes.
+ */
+export interface Readiness {
+    needsOperator: boolean;
+    needsBaseAllowance: boolean;
+    needsQuoteAllowance: boolean;
+}
+export declare function checkReadiness(c: LogswapClient, key: PoolKey, owner: Address, need?: {
+    base?: bigint;
+    quote?: bigint;
+    positions?: boolean;
+}): Promise<Readiness>;

package/dist/claims.js

@@ -0,0 +1,98 @@
+/**
+ * claims.ts — fee claims, and the ERC-6909 operator grant every router write depends on.
+ *
+ * Note the two unrelated meanings of "claim" in this protocol, kept apart here:
+ *   - a FEE claim   — `claimFees`, withdrawing accrued quote while the position stays whole
+ *   - a TOKEN claim — a bearer IOU (bit-255-clear id) for inventory parked inside the manager
+ */
+import { cPoolManagerAbi, logswapRouterAbi } from "./generated.js";
+import { isPosition } from "./ids.js";
+import { requireWallet, resolveDeadline, resolveRecipient, sendRouterWrite } from "./write.js";
+/**
+ * Claim accrued fees across one or more classes: one transfer, positions untouched.
+ *
+ * **Every id must be REGISTERED** — one the manager has seen minted. An id for a class that has
+ * never existed reverts the whole batch with `WrongPool`, because an unregistered id has
+ * `poolId == 0` and cannot be shown to belong to this pool. In a contract holding every market's
+ * assets, "cannot be shown to belong" must not be read as "belongs". A class that exists but which
+ * the caller does not hold is fine — that is a no-op, not a revert.
+ */
+export async function claimFees(c, a) {
+    for (const id of a.ids) {
+        if (!isPosition(id)) {
+            throw new Error(`logswap: id ${id} is a TOKEN claim (bit 255 clear), not a position — it has no fees to claim.`);
+        }
+    }
+    return sendRouterWrite(c, {
+        abi: logswapRouterAbi,
+        functionName: "claim",
+        args: [a.key, a.ids, resolveRecipient(c, a), resolveDeadline(a)],
+    });
+}
+/**
+ * Grant the router operator rights over your ERC-6909 positions.
+ *
+ * **Required before any burn, update, move or harvest** — those pull the shares to the router
+ * first. Without it they revert on the transfer, which reads as an unrelated balance error. Swaps
+ * and mints do not need it.
+ *
+ * One grant covers every market, because the positions all live in the one manager.
+ */
+export async function approveRouterAsOperator(c, approved = true) {
+    const { account } = requireWallet(c);
+    return c.wallet.writeContract({
+        address: c.addresses.cPoolManager,
+        abi: cPoolManagerAbi,
+        functionName: "setOperator",
+        args: [c.addresses.router, approved],
+        account,
+        chain: c.wallet.chain,
+    });
+}
+/** Is the router already an operator for `owner`? Check before prompting for a signature. */
+export async function isRouterApproved(c, owner) {
+    return c.public.readContract({
+        address: c.addresses.cPoolManager,
+        abi: cPoolManagerAbi,
+        functionName: "isOperator",
+        args: [owner, c.addresses.router],
+    });
+}
+export async function checkReadiness(c, key, owner, need = {}) {
+    const erc20 = [
+        {
+            type: "function",
+            name: "allowance",
+            stateMutability: "view",
+            inputs: [
+                { name: "owner", type: "address" },
+                { name: "spender", type: "address" },
+            ],
+            outputs: [{ type: "uint256" }],
+        },
+    ];
+    const [operator, baseAllow, quoteAllow] = await Promise.all([
+        need.positions ? isRouterApproved(c, owner) : Promise.resolve(true),
+        need.base
+            ? c.public.readContract({
+                address: key.base,
+                abi: erc20,
+                functionName: "allowance",
+                args: [owner, c.addresses.router],
+            })
+            : Promise.resolve(0n),
+        need.quote
+            ? c.public.readContract({
+                address: key.quote,
+                abi: erc20,
+                functionName: "allowance",
+                args: [owner, c.addresses.router],
+            })
+            : Promise.resolve(0n),
+    ]);
+    return {
+        needsOperator: !operator,
+        needsBaseAllowance: need.base !== undefined && baseAllow < need.base,
+        needsQuoteAllowance: need.quote !== undefined && quoteAllow < need.quote,
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,68 @@
+/**
+ * client.ts — the SDK handle: addresses + viem clients.
+ *
+ * Construct once and pass to every helper. `wallet` is optional: read helpers need only `public`.
+ *
+ * **Three addresses, permanently.** Not three per market — every market lives in the one manager,
+ * and a market is an `initialize(key, x0)` call rather than a deployment. So this is a constant of
+ * the protocol, not configuration that grows.
+ */
+import type { Address, PublicClient, WalletClient } from "viem";
+export interface LogswapAddresses {
+    /** The C singleton — a floor per position, on a tick ladder. ERC-6909 positions and token
+     *  claims live here. */
+    cPoolManager: Address;
+    /** User entry for every market: multicall, blended mint, zap, routes, Permit2. */
+    router: Address;
+    /** Read-only: ladder derivations and revert-quoter previews. */
+    lens: Address;
+    /**
+     * The F-pool singleton — fungible claims, one shared floor, n bases. Optional only because a
+     * deployment predating it will not carry the address; every F-pool call needs it.
+     */
+    fPoolManager?: Address;
+    /** Optional — the router falls back to plain approvals when absent. */
+    permit2?: Address;
+}
+export interface LogswapClient {
+    public: PublicClient;
+    wallet?: WalletClient;
+    addresses: LogswapAddresses;
+}
+export declare function createLogswapClient(args: {
+    public: PublicClient;
+    wallet?: WalletClient;
+    addresses: LogswapAddresses;
+}): LogswapClient;
+/**
+ * Assert the deployment matches the ABI this build was generated against.
+ *
+ * Cheap insurance worth taking at construction: without it, a manager from a different deployment
+ * decodes into plausible-looking garbage rather than failing. `version` is bumped on any tier-1 or
+ * tier-2 change (docs/app.md).
+ *
+ * **2** since 2026-09-01. It sat at 1 across a read surface that changed underneath it — the nine
+ * `public constant` getters left the manager for `CParams`, `move` gained its settlement bounds,
+ * `createMarket` arrived — so a 1 answered for two incompatible ABIs and this check passed against
+ * a manager it should have rejected. Observed, not theorised: a local chain running a pre-trim
+ * manager sailed through `assertVersion` while `FEE_MAX()` still answered on it. Move this in the
+ * same change as `CParams.VERSION`, never after it.
+ *
+ * **3** since 2026-09-03 (contracts `d8406fb`): `burnById` and `update` take an `owner`, `update`
+ * mints to `to`, `positions()` returns `aps` as uint128 — and a returned quote flow now carries the
+ * swept fees (decisions 018), which is why `exit`'s settle-to-one-asset math changed with it.
+ */
+export declare const EXPECTED_VERSION = 3n;
+/**
+ * The F manager's own tag (contracts 25a7bcf: 5 — the key's salt, pool names, the sponsor registry;
+ * 4 was the income-only harvest cut).
+ *
+ * A FLOOR, not an equality — unlike `EXPECTED_VERSION` above. The F primitive is iterating fast and
+ * its bumps are mostly additive (6 is `multicall`, which nothing this SDK calls goes near), so an
+ * exact match meant each one bricked every app on the deployment until the SDK was republished — a
+ * version wall in front of a change that broke nothing. The cost is that a genuinely breaking bump
+ * passes it; when one lands, raise this constant in the same change, which is the discipline
+ * `EXPECTED_VERSION` enforces mechanically and this one asks for.
+ */
+export declare const EXPECTED_F_VERSION = 5n;
+export declare function assertVersion(c: LogswapClient, expected?: bigint): Promise<void>;