@logswap/sdk 0.5.35

package/src/actions.ts

@@ -0,0 +1,207 @@
+/**
+ * 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, type Address, type Hash, type Hex } from "viem";
+import { logswapRouterAbi } from "./generated.js";
+import type { LogswapClient } from "./client.js";
+import type { PoolKey } from "./keys.js";
+import { NO_CAP } from "./ids.js";
+import type { Hop } from "./swap.js";
+import { resolveDeadline, resolveRecipient, sendRouterWriteWithPermits, simulateRouterWrite, type WriteOptions } 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 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;
+}
+
+/* payload encoding ========================================================== */
+
+function payloadType(encoder: string) {
+  const f = (logswapRouterAbi as readonly { type: string; name?: string; inputs?: readonly unknown[] }[]).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: string, value: unknown): Hex => encodeAbiParameters(payloadType(encoder) as never, [value] as never);
+
+/** Mint exposure `L` at `targetFloor` (off-grid blends the two adjacent rungs), `cap` optional. */
+export function mintAction(a: { key: PoolKey; targetFloor: bigint; cap?: bigint; L: bigint }): Action {
+  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: { key: PoolKey; ids: readonly bigint[]; shares: readonly bigint[] }): Action {
+  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: { key: PoolKey; baseIn: boolean; amountIn: bigint; minOut?: bigint }): Action {
+  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: { key: PoolKey; baseOut: boolean; amountOut: bigint; maxIn?: bigint }): Action {
+  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: { key: PoolKey; ids: readonly bigint[] }): Action {
+  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: {
+  key: PoolKey;
+  fromId: bigint;
+  shares: bigint;
+  toFloor: bigint;
+  toCap?: bigint;
+  newL: bigint;
+}): Action {
+  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: { hops: readonly Hop[]; amountIn: bigint; minOut?: bigint }): Action {
+  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: {
+  tokens: readonly Address[];
+  maxIn?: readonly bigint[];
+  minOut?: readonly bigint[];
+  recipient: Address;
+}): Settle {
+  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 };
+}
+
+export interface PairBounds {
+  maxBaseIn?: bigint;
+  maxQuoteIn?: bigint;
+  minBaseOut?: bigint;
+  minQuoteOut?: bigint;
+}
+
+/** Settle both of a market's tokens, in kind. */
+export function settleInKind(key: PoolKey, recipient: Address, b: PairBounds = {}): Settle {
+  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: PoolKey, recipient: Address, side: "base" | "quote", b: { maxIn?: bigint; minOut?: bigint } = {}): Settle {
+  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,
+  });
+}
+
+/* the batch ================================================================= */
+
+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 async function execute(c: LogswapClient, a: ExecuteArgs): Promise<Hash> {
+  const settle: 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: LogswapClient,
+  a: ExecuteArgs & { account?: Address },
+): Promise<{ results: readonly Hex[]; flows: readonly bigint[] }> {
+  const settle: Settle = { ...a.settle, recipient: a.settle.recipient ?? a.account ?? resolveRecipient(c, a) };
+  const [results, flows] = await simulateRouterWrite<readonly [readonly Hex[], readonly bigint[]]>(c, {
+    abi: logswapRouterAbi,
+    functionName: "execute",
+    args: [a.actions, settle, resolveDeadline(a)],
+    account: a.account,
+  });
+  return { results, flows };
+}

package/src/admin.ts

@@ -0,0 +1,33 @@
+/**
+ * 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";
+import { cPoolManagerAbi, fPoolManagerAbi } from "./generated.js";
+
+function wallet(c: LogswapClient) {
+  if (!c.wallet) throw new Error("a wallet client is required");
+  return c.wallet;
+}
+
+export async function setProtocolFeeCut(c: LogswapClient, cutWad: bigint): Promise<Hash> {
+  return wallet(c).writeContract({ address: c.addresses.cPoolManager, abi: cPoolManagerAbi, functionName: "setProtocolFeeCut", args: [cutWad], chain: c.wallet!.chain, account: c.wallet!.account! } as never);
+}
+export async function setFeeParams(c: LogswapClient, mintFeeProtocolCutWad: bigint, harvestFeeWad: bigint): Promise<Hash> {
+  return wallet(c).writeContract({ address: c.addresses.fPoolManager as Address, abi: fPoolManagerAbi, functionName: "setFeeParams", args: [mintFeeProtocolCutWad, harvestFeeWad], chain: c.wallet!.chain, account: c.wallet!.account! } as never);
+}
+export async function setHarvestFeeExempt(c: LogswapClient, poolId: Hex, exempt: boolean): Promise<Hash> {
+  return wallet(c).writeContract({ address: c.addresses.fPoolManager as Address, abi: fPoolManagerAbi, functionName: "setHarvestFeeExempt", args: [poolId, exempt], chain: c.wallet!.chain, account: c.wallet!.account! } as never);
+}
+export async function proposeCollector(c: LogswapClient, side: "C" | "F", next: Address): Promise<Hash> {
+  const address = side === "C" ? c.addresses.cPoolManager : (c.addresses.fPoolManager as Address);
+  const abi = side === "C" ? cPoolManagerAbi : fPoolManagerAbi;
+  return wallet(c).writeContract({ address, abi, functionName: "proposeCollector", args: [next], chain: c.wallet!.chain, account: c.wallet!.account! } as never);
+}
+export async function acceptCollector(c: LogswapClient, side: "C" | "F"): Promise<Hash> {
+  const address = side === "C" ? c.addresses.cPoolManager : (c.addresses.fPoolManager as Address);
+  const abi = side === "C" ? cPoolManagerAbi : fPoolManagerAbi;
+  return wallet(c).writeContract({ address, abi, functionName: "acceptCollector", args: [], chain: c.wallet!.chain, account: c.wallet!.account! } as never);
+}

package/src/claims.ts

@@ -0,0 +1,132 @@
+/**
+ * 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 { cPoolManagerAbi, logswapRouterAbi } from "./generated.js";
+import type { LogswapClient } from "./client.js";
+import type { PoolKey } from "./keys.js";
+import { isPosition } from "./ids.js";
+import { requireWallet, resolveDeadline, resolveRecipient, sendRouterWrite, 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 async function claimFees(c: LogswapClient, a: ClaimFeesArgs): Promise<Hash> {
+  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: LogswapClient, approved = true): Promise<Hash> {
+  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,
+  } as never);
+}
+
+/** Is the router already an operator for `owner`? Check before prompting for a signature. */
+export async function isRouterApproved(c: LogswapClient, owner: Address): Promise<boolean> {
+  return c.public.readContract({
+    address: c.addresses.cPoolManager,
+    abi: cPoolManagerAbi,
+    functionName: "isOperator",
+    args: [owner, c.addresses.router],
+  }) as 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 async function checkReadiness(
+  c: LogswapClient,
+  key: PoolKey,
+  owner: Address,
+  need: { base?: bigint; quote?: bigint; positions?: boolean } = {},
+): Promise<Readiness> {
+  const erc20 = [
+    {
+      type: "function",
+      name: "allowance",
+      stateMutability: "view",
+      inputs: [
+        { name: "owner", type: "address" },
+        { name: "spender", type: "address" },
+      ],
+      outputs: [{ type: "uint256" }],
+    },
+  ] as const;
+
+  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],
+        }) as Promise<bigint>)
+      : Promise.resolve(0n),
+    need.quote
+      ? (c.public.readContract({
+          address: key.quote,
+          abi: erc20,
+          functionName: "allowance",
+          args: [owner, c.addresses.router],
+        }) as Promise<bigint>)
+      : Promise.resolve(0n),
+  ]);
+
+  return {
+    needsOperator: !operator,
+    needsBaseAllowance: need.base !== undefined && baseAllow < need.base,
+    needsQuoteAllowance: need.quote !== undefined && quoteAllow < need.quote,
+  };
+}

package/src/client.ts

@@ -0,0 +1,104 @@
+/**
+ * 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 function createLogswapClient(args: {
+  public: PublicClient;
+  wallet?: WalletClient;
+  addresses: LogswapAddresses;
+}): LogswapClient {
+  return { public: args.public, wallet: args.wallet, addresses: args.addresses };
+}
+
+/**
+ * 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 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 const EXPECTED_F_VERSION = 5n;
+
+export async function assertVersion(c: LogswapClient, expected = EXPECTED_VERSION): Promise<void> {
+  const { cPoolManagerAbi } = await import("./generated.js");
+  const got = await c.public.readContract({
+    address: c.addresses.cPoolManager,
+    abi: cPoolManagerAbi,
+    functionName: "version",
+  });
+  if (got !== expected) {
+    throw new Error(
+      `logswap: manager at ${c.addresses.cPoolManager} reports version ${got}, but this SDK was built ` +
+        `against version ${expected}. Upgrade the SDK or point at the matching deployment.`,
+    );
+  }
+  // the F manager carries its own tag since contracts c782811; assert it the same way when deployed
+  if (c.addresses.fPoolManager) {
+    const { fPoolManagerAbi } = await import("./generated.js");
+    const gotF = await c.public.readContract({
+      address: c.addresses.fPoolManager,
+      abi: fPoolManagerAbi,
+      functionName: "version",
+    });
+    if (gotF < EXPECTED_F_VERSION) {
+      throw new Error(
+        `logswap: F manager at ${c.addresses.fPoolManager} reports version ${gotF}, but this SDK needs ` +
+          `at least F version ${EXPECTED_F_VERSION}. Upgrade the deployment or point at a newer one.`,
+      );
+    }
+  }
+}