@logswap/sdk 0.5.55 → 0.5.57

package/src/fpool.ts

@@ -4,7 +4,7 @@
  * The other primitive. `CPoolManager` gives every position its own floor on a tick ladder;
  * `FPoolManager` gives every share the SAME floor and deletes the ladder, the accumulators and the
  * per-position accounting with it. Reading the two side by side is the fastest way to understand
- * either (logswap-docs:docs/multi/f-pool.md).
+ * either.
  *
  * **A pool is an ID, not an address.** Both primitives are singletons now, so neither has a
  * per-pool deployment — but they are addressed differently and for a reason. The C manager rides
@@ -15,7 +15,7 @@
  * **Two products, one contract.** The basket (n > 1) and the launch (n = 1, the creator alone on
  * the lever) are the same bytecode under two key fields — the KIND (what the manager promises
  * structurally) and the POLICY (the pool's policy: its roles, its gates, the terms of every harvest
- * and release; decisions 041, 044) — and nothing in the maths. `describeFPool` below reports
+ * and release) — and nothing in the maths. `describeFPool` below reports
  * which shape a given pool is, because a UI has to decide what to render.
  *
  * **The roles are the policy's, not the manager's** (F version 15). The manager holds no
@@ -34,9 +34,9 @@ import { encodeFunctionData, toFunctionSelector, type Address, type Hash, type H
 import { fPoolManagerAbi, logswapRouterAbi, padPolicyAbi, polPolicyAbi, policyRegistryAbi, privatePolicyAbi, publicPolicyAbi } from "./generated.js";
 
 /**
- * One contract, one ABI (decisions 039, F version 12): `harvest`, `claim`, `retire`, `regenerate`,
+ * One contract, one ABI (F version 12): `harvest`, `claim`, `retire`, `regenerate`,
  * `setLegs`, the names, the fee parameters are `FPoolManager`'s own code. The roles left it for
- * the policies in F version 15 (decisions 044): {@link fPolicyBaseAbi} is what every policy shares,
+ * the policies in F version 15: {@link fPolicyBaseAbi} is what every policy shares,
  * {@link privatePolicyAbi} the desk's, {@link padPolicyAbi} / {@link polPolicyAbi} / {@link publicPolicyAbi}
  * the kinds'.
  */
@@ -48,12 +48,12 @@ export { fPoolManagerAbi, padPolicyAbi, polPolicyAbi, privatePolicyAbi, publicPo
  */
 export const fPolicyBaseAbi = polPolicyAbi;
 import type { LogswapClient } from "./client.js";
-import { signerFor } from "./write.js";
+import { fallBackUnlessRejected, signerFor } from "./write.js";
 
 const WAD = 10n ** 18n;
 const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000" as const;
 
-/** The optional questions a policy declared at birth (decisions 044), as bits of `Pool.asks`. */
+/** The optional questions a policy declared at birth, as bits of `Pool.asks`. */
 export const ASK_SWAP = 1;
 export const ASK_MINT = 2;
 
@@ -82,29 +82,29 @@ export interface FPoolState {
   /** Σ = ∫ Σ_j w_j (dx_j)², accrued even though the fee is fixed — the kernel stays calculable. */
   bigSigma: bigint;
   /**
-   * The pool's policy (decisions 041, 044): the contract the key names, holding the pool's roles
+   * The pool's policy: the contract the key names, holding the pool's roles
    * and answering every question the manager does not decide itself. Read its roles with
    * {@link getFPoolRoles}; one of the deployment's four ({@link fPoolPolicyFor}) on every protocol pool.
    */
   policy: Address;
   /** Whether the policy asked to be consulted on swaps ({@link ASK_SWAP}) and mints ({@link ASK_MINT}) — the desk's policy does, no other. */
   asks: number;
-  /** The sponsor's own label for this pool — the policy's word (decisions 049), mutable and never identity. "" when unnamed. */
+  /** The sponsor's own label for this pool — the policy's word, mutable and never identity. "" when unnamed. */
   name: string;
   /** The block of the last harvest / composition action: no swap runs in it. */
   restructureBlock: number;
-  /** What the pool is — its POLICY's self-description (decisions 049); see {@link FPoolKind}. */
+  /** What the pool is — its POLICY's self-description; see {@link FPoolKind}. */
   kind: FPoolKind;
-  /** False before the first seed — and between a retire and the next one (decisions 032). */
+  /** False before the first seed — and between a retire and the next one. */
   seeded: boolean;
   /**
-   * The live GENERATION (decisions 032). Every retire freezes one into a bundle its shares
+   * The live GENERATION. Every retire freezes one into a bundle its shares
    * redeem ({@link fPoolRedeem}) and opens the next; the share id carries it
    * ({@link fPoolShareId}), so generations `0 … gen-1` are retired claims and `gen` is the pool.
    */
   gen: number;
   totalSupply: bigint;
-  /** What the pool holds of each base — the STATE since decisions 026; the mark `x` is derived from it. */
+  /** What the pool holds of each base — the STATE; the mark `x` is derived from it. */
   reserves: bigint[];
 }
 
@@ -149,8 +149,8 @@ export async function getFPool(c: LogswapClient, poolId: Hex): Promise<FPoolStat
   const n = Number(p.n);
   const idx = Array.from({ length: n }, (_, i) => BigInt(i));
   const [theta, compositeX, legs, kind, name] = await Promise.all([
-    // before the seed there is no L and no floor: θ is X by convention (the manager says so since
-    // bd3dd87's successor; older deployments revert with DivWadFailed, so do not ask them)
+    // before the seed there is no L and no floor: θ is X by convention (older deployments revert
+    // with DivWadFailed, so do not ask them)
     p.L > 0n ? rd<bigint>("theta", [poolId]) : rd<bigint>("compositeX", [poolId]),
     rd<bigint>("compositeX", [poolId]),
     Promise.all(idx.map((i) => rd<readonly [Address, bigint, bigint, bigint]>("legOf", [poolId, i]))),
@@ -160,7 +160,7 @@ export async function getFPool(c: LogswapClient, poolId: Hex): Promise<FPoolStat
 
   const bases = legs.map((l) => l[0]);
   const weights = legs.map((l) => l[1]);
-  const x = legs.map((l) => l[2]); // derived by the manager: x_j = ln(w_j·L / R_j) (decisions 026)
+  const x = legs.map((l) => l[2]); // derived by the manager: x_j = ln(w_j·L / R_j) 
   const reserves = legs.map((l) => l[3]); // the state
   const { quote, Q, L, phi, theta0, bigSigma, policy, restructureBlock, seeded, gen } = p;
   const totalSupply = p.shares;
@@ -191,7 +191,7 @@ export async function getFPool(c: LogswapClient, poolId: Hex): Promise<FPoolStat
 }
 
 /**
- * The kind of pool — the POLICY's self-description (decisions 049: the manager knows no kind; the
+ * The kind of pool — the POLICY's self-description (the manager knows no kind; the
  * policy the key names is the kind, and what it promises is its code). `public`: the protocol's
  * own pool — its policy requires the collector as creator; no gate, no operator. `private`, the
  * desk: the one whose policy may gate swaps and mints, with an operator that reshapes the legs
@@ -209,7 +209,7 @@ const kindCache = new Map<string, Promise<FPoolKind>>();
 
 /**
  * What a policy IS — its `kind()` tag, read once per policy address and cached for the client's
- * chain: a pool's kind is its policy's word (decisions 049), never the manager's. An unknown tag
+ * chain: a pool's kind is its policy's word, never the manager's. An unknown tag
  * (a policy that is not one of the protocol's four shapes) throws; the app has no screen for it.
  */
 export function fPoolKindOfPolicy(c: LogswapClient, policy: Address): Promise<FPoolKind> {
@@ -227,14 +227,14 @@ export function fPoolKindOfPolicy(c: LogswapClient, policy: Address): Promise<FP
   return hit;
 }
 
-/** The pool's label, as its policy holds it (decisions 049). "" when unnamed. */
+/** The pool's label, as its policy holds it. "" when unnamed. */
 export async function fPoolNameOf(c: LogswapClient, poolId: Hex, policy?: Address): Promise<string> {
   const p = policy ?? (await fPoolPolicyOf(c, poolId));
   const word = (await c.public.readContract({ address: p, abi: fPolicyBaseAbi, functionName: "nameOf", args: [poolId] } as never)) as Hex;
   return bytes32ToText(word);
 }
 
-/** The deployment's policy for a kind (decisions 044, 049): the protocol's policy that IS that kind. */
+/** The deployment's policy for a kind: the protocol's policy that IS that kind. */
 export function fPoolPolicyFor(c: LogswapClient, kind: FPoolKind): Address {
   const a = c.addresses;
   const policy = kind === "public" ? a.publicPolicy : kind === "private" ? a.privatePolicy : kind === "pol" ? a.polPolicy : a.padPolicy;
@@ -255,7 +255,7 @@ export async function fPoolPolicyOf(c: LogswapClient, poolId: Hex): Promise<Addr
 }
 
 /**
- * A pool's roles, as its POLICY holds them (decisions 044). `creator` is immutable identity —
+ * A pool's roles, as its POLICY holds them. `creator` is immutable identity —
  * who was born holding the pool; `authority` is the cold key that owns it now, the creator until
  * a two-step handover; on the desk's kind the `operator` runs it (zero = the authority itself,
  * {@link fPoolOperatorOf}) and the two gates and the list are its. Every other kind has no
@@ -265,7 +265,7 @@ export interface FPoolRoles {
   policy: Address;
   creator: Address;
   authority: Address;
-  /** The proposed next authority, until it accepts — zero when nothing is pending (decisions 020). */
+  /** The proposed next authority, until it accepts — zero when nothing is pending. */
   pendingAuthority: Address;
   operator: Address;
   pendingOperator: Address;
@@ -303,7 +303,7 @@ export type FPoolShape = "launch" | "basket";
 
 export interface FPoolDescription {
   shape: FPoolShape;
-  /** The pad is the launch shape, by the kind (decisions 036). */
+  /** The pad is the launch shape, by the kind. */
   legs: number;
   /** True when the pool holds no quote: an all-base resting ask. base→quote is the one blocked path. */
   atFloor: boolean;
@@ -315,7 +315,7 @@ export interface FPoolDescription {
   unharvested: bigint;
   /** The most a harvest may take now by the KIND's promise: the bid, and on a pad the income. The policy may allow less — {@link FPoolRoles.maxHarvest}. */
   harvestable: bigint;
-  /** The dead shares' banked dividend — a pad's pot, the creator's income until a rung is climbed (decisions 041). */
+  /** The dead shares' banked dividend — a pad's pot, the creator's income until a rung is climbed. */
   pot: bigint;
 }
 
@@ -332,7 +332,7 @@ export async function describeFPool(c: LogswapClient, s: FPoolState): Promise<FP
     ? await Promise.all([rd<bigint>("unharvested"), rd<bigint>("harvestable"), rd<bigint>("dividendOf", [s.poolId, BigInt(s.gen), DEAD_ADDRESS])])
     : [0n, 0n, 0n];
   return {
-    shape: s.kind === "pad" ? "launch" : "basket", // the kind, not n = 1 (decisions 036)
+    shape: s.kind === "pad" ? "launch": "basket", // the kind, not n = 1 
     legs: s.bases.length,
     atFloor: s.Q === 0n,
     unharvested,
@@ -353,7 +353,7 @@ export function fPoolShareValue(s: FPoolState): bigint {
 }
 
 // ─── swaps ────────────────────────────────────────────────────────────────────
-// Exact-in only (f-pool §10). Three paths; the third is the one that makes a basket a basket.
+// Exact-in only. Three paths; the third is the one that makes a basket a basket.
 
 export interface FPoolSwapArgs {
   poolId: Hex;
@@ -422,7 +422,7 @@ export async function fPoolMint(
 
 /**
  * Burn shares for the pro-rata slice of every reserve. Available at any Q, and after dissolution.
- * By owner since contracts `c782811` (decisions 019): the account burns its own shares; an
+ * By owner: the account burns its own shares; an
  * operator may pass another owner's address, as on the C manager's `burnById`.
  */
 export async function fPoolBurn(
@@ -473,7 +473,7 @@ export async function fPoolPreviewZapIn(c: LogswapClient, poolId: Hex, dL: bigin
  *
  * The imbalanced part goes through the pool's own curve before anything is minted. That is not a
  * penalty: minting against a quote-only deposit would be a zero-slippage, zero-fee swap at stale
- * spot, paid for by the existing LPs — 27.4% in f-pool §6's worked example. Routing it through
+ * spot, paid for by the existing LPs. Routing it through
  * the curve deletes the subsidy and hands the fee and impact to the incumbents instead.
  */
 export async function fPoolZapIn(
@@ -532,7 +532,7 @@ export async function fPoolPreviewZapOut(
 }
 
 /**
- * Roll a retired generation's bundle into the pool's live one (decisions 025, 032), on the
+ * Roll a retired generation's bundle into the pool's live one, on the
  * router under one lock: redeem `shares` of generation `gen` in place — the legs, the quote and
  * any unpulled dividend come back — buy through the pool's own curve only what the live
  * generation's ratio lacks, mint `dL` of it to `to`, and refund the rest in kind. Quote the
@@ -592,11 +592,11 @@ export async function fPoolPreviewRollIn(
 // ─── the floor lever (authority only) ─────────────────────────────────────────
 
 /**
- * Remove quote, lifting θ — price-neutral, no base moves, and since decisions 028 a DIVIDEND to
+ * Remove quote, lifting θ — price-neutral, no base moves, and a DIVIDEND to
  * every share: the amount goes into the pool's pot and each holder's slice is settled lazily on
  * their next transfer, mint or burn, or pulled with {@link fPoolClaim}. The sponsor's own slice —
  * its shares' and the locked seed's at 0xdead — is pushed to `to` at once. On a pad
- * the lift stops at the seed floor θ₀ (income only); nothing else bounds it (decisions 035) — an
+ * the lift stops at the seed floor θ₀ (income only); nothing else bounds it — an
  * unlocked pool's authority may take Q to zero.
  */
 export async function fPoolHarvest(c: LogswapClient, a: { poolId: Hex; amount: bigint; to?: Address; account: Address }) {
@@ -604,16 +604,16 @@ export async function fPoolHarvest(c: LogswapClient, a: { poolId: Hex; amount: b
 }
 
 /**
- * Pull one's settled dividend (decisions 028) on a generation's shares without moving them;
+ * Pull one's settled dividend on a generation's shares without moving them;
  * anyone with shares. `gen` defaults to the live generation; a retired generation's harvests
- * stay claimable under its own id (decisions 032).
+ * stay claimable under its own id.
  */
 export async function fPoolClaim(c: LogswapClient, a: { poolId: Hex; gen?: bigint | number; to?: Address; account: Address }) {
   const gen = a.gen ?? (await fPoolGen(c, a.poolId));
   return writeFPool(c, a.poolId, "claim", [BigInt(gen), a.to ?? a.account], a.account);
 }
 
-/** A holder's dividend as of now on generation `gen` (the live one by default) — banked plus pending on the current balance (decisions 028). */
+/** A holder's dividend as of now on generation `gen` (the live one by default) — banked plus pending on the current balance. */
 export async function fPoolDividendOf(c: LogswapClient, poolId: Hex, holder: Address, gen?: bigint | number): Promise<bigint> {
   const g = gen ?? (await fPoolGen(c, poolId));
   return c.public.readContract({
@@ -676,7 +676,7 @@ async function writeRouter(
   let sendArgs: unknown[] = args;
   if (pullTokens.length) {
     const { permit2SigCalls } = await import("./onboard.js");
-    const sigCalls = await permit2SigCalls(c, pullTokens).catch(() => []);
+    const sigCalls = await permit2SigCalls(c, pullTokens).catch(fallBackUnlessRejected);
     if (sigCalls.length) {
       const { encodeFunctionData } = await import("viem");
       const inner = encodeFunctionData({ abi: logswapRouterAbi, functionName, args } as never);
@@ -762,7 +762,7 @@ export async function approveRouterForFPool(c: LogswapClient, account: Address)
 // a multicall that uses it.
 
 /**
- * The ERC-6909 id carrying generation `gen` of a pool's shares (decisions 032): bit 255 set (the
+ * The ERC-6909 id carrying generation `gen` of a pool's shares: bit 255 set (the
  * share flag), the pool id's top 239 bits, the generation in the low 16. Each generation's shares
  * are their own asset — a retired one is a claim on its bundle, the live one on the pool.
  */
@@ -802,7 +802,7 @@ export async function fPoolShareBalance(c: LogswapClient, poolId: Hex, owner: Ad
   } as never) as Promise<bigint>;
 }
 
-/** A retired generation's bundle (decisions 032): what is left to redeem — supply, quote, base per leg index. */
+/** A retired generation's bundle: what is left to redeem — supply, quote, base per leg index. */
 export async function fPoolBundleOf(
   c: LogswapClient,
   poolId: Hex,
@@ -826,7 +826,7 @@ export interface FPoolClaimRow {
   dividend: bigint;
 }
 
-/** A holder's claims on a pool's retired generations — one row per generation still held (decisions 032). */
+/** A holder's claims on a pool's retired generations — one row per generation still held. */
 export async function fPoolClaimsOf(c: LogswapClient, poolId: Hex, owner: Address): Promise<FPoolClaimRow[]> {
   const { logswapLensAbi } = await import("./generated.js");
   const rows = (await c.public.readContract({
@@ -839,7 +839,7 @@ export async function fPoolClaimsOf(c: LogswapClient, poolId: Hex, owner: Addres
 }
 
 /**
- * Redeem `shares` of a RETIRED generation (decisions 032): its bundle, pro rata — the base per
+ * Redeem `shares` of a RETIRED generation: its bundle, pro rata — the base per
  * leg and the quote — plus the owner's settled dividend. Not `burn`: nothing can move a bundle's
  * ratio, so there is no slippage to bound. The owner, or an operator of theirs.
  */
@@ -943,7 +943,7 @@ export interface FPoolCreateArgs {
    */
   kind: FPoolKind;
   /**
-   * The pool's policy (decisions 041, 044, 049): the contract the key names, approved by the
+   * The pool's policy: the contract the key names, approved by the
    * registry, and the pool's kind. Defaults to the deployment's policy for `kind`
    * ({@link fPoolPolicyFor}) — the one every protocol pool names.
    */
@@ -1025,8 +1025,8 @@ export async function fPoolIdOf(c: LogswapClient, a: Omit<FPoolCreateArgs, "acco
 }
 
 /**
- * The reserve a leg holds at a mark: `R = Lj·e^{−x}`, WAD math. The seed names RESERVES since
- * decisions 029 — the sponsor states holdings and the price follows, `p = Lj / R` — so this is
+ * The reserve a leg holds at a mark: `R = Lj·e^{−x}`, WAD math. The seed names RESERVES —
+ * the sponsor states holdings and the price follows, `p = Lj / R` — so this is
  * the one conversion from a price to what the pool will hold, done here, on the way in. Float
  * precision (~1e-16 relative) is what a seed needs: any reserve is a legal seed, and the mark
  * the pool derives from it is the one the sponsor meant to within that.
@@ -1052,7 +1052,7 @@ export async function fPoolSeed(
 }
 
 /**
- * Retire the live generation (decisions 025, 032, 035) — the raw entry (`dissolve` before F
+ * Retire the live generation — the raw entry (`dissolve` before F
  * version 14). Allowed only at an empty bid, Q ≤ L/1e9, on every pool: the market took it, or the
  * operator harvested it out first ({@link fPoolRetire} does both in one transaction). The live
  * (S, Q, R_j) become a frozen bundle every share of this generation redeems ({@link fPoolRedeem})
@@ -1080,23 +1080,23 @@ export async function fPoolRetire(c: LogswapClient, a: { poolId: Hex; account: A
 
 /**
  * The harvests that empty an unlocked pool's bid, in order — what a relaunch sends before its
- * `retire` (decisions 035: a retire needs an empty bid on every pool). Since F version 14 one
+ * `retire` (a retire needs an empty bid on every pool). Since F version 14 one
  * `harvest(Q)` does it: the protocol's cut leaves the pool with the amount (with no collector
  * there is no cut). `[]` when the bid is already empty. Throws on a pad that still bids (its bid
  * empties only as the market sells it down), and when the pool's policy keeps a floor on the bid
- * (`PolPolicy.keepQuote`, decisions 044): a `retire` under that policy waits for the market.
+ * (`PolPolicy.keepQuote`): a `retire` under that policy waits for the market.
  */
 export async function fPoolEmptyingHarvests(c: LogswapClient, poolId: Hex): Promise<bigint[]> {
   const s = await getFPool(c, poolId);
   if (s.Q === 0n) return [];
-  if (s.kind === "pad") throw new Error("logswap: a pad is retired only once its bid is empty (decisions 035)");
+  if (s.kind === "pad") throw new Error("logswap: a pad is retired only once its bid is empty");
   const { maxHarvest } = await getFPoolRoles(c, poolId, s);
-  if (maxHarvest < s.Q) throw new Error("logswap: the pool's policy keeps a floor on the bid — it cannot be harvested empty (decisions 044)");
+  if (maxHarvest < s.Q) throw new Error("logswap: the pool's policy keeps a floor on the bid — it cannot be harvested empty");
   return [s.Q];
 }
 
 /**
- * Release the dead shares' pot under the policy's terms (decisions 041, 044) — a pad's graduation.
+ * Release the dead shares' pot under the policy's terms — a pad's graduation.
  * The manager harvests the generation's income first (the pot then holds everything the dead
  * shares earned), asks the policy, and applies its answer: a share to the payee it names (the pad's
  * creator — the pool's authority), a cut to the collector, the rest bought in as more of the
@@ -1108,7 +1108,7 @@ export async function fPoolRegenerate(c: LogswapClient, a: { poolId: Hex; to?: A
 }
 
 /**
- * The relaunch as ONE transaction (decisions 025, 032, 035, 037): `harvest` the bid out — a
+ * The relaunch as ONE transaction: `harvest` the bid out — a
  * dividend to every share, {@link fPoolEmptyingHarvests} — `retire` the live generation at the
  * empty bid, `redeem` the caller's own shares of it (when `shares` > 0), optionally `setLegs` the
  * next generation's composition (`legs`: a private pool's reshape — retire, admit, reweight), and
@@ -1127,7 +1127,7 @@ export async function fPoolRelaunch(
     shares: bigint;
     L0: bigint;
     Q0: bigint;
-    /** the next generation's composition (decisions 037): one weight per existing leg (0 retires it), then one per new base */
+    /** the next generation's composition: one weight per existing leg (0 retires it), then one per new base */
     legs?: { weights: bigint[]; newBases?: Address[] };
     extra?: Hex[];
     account: Address;
@@ -1148,7 +1148,7 @@ export async function fPoolRelaunch(
   return writeFPool0(c, "multicall", [calls], a.account);
 }
 
-/** Where a pad's seed lives (decisions 036): `seed` mints every share of a pad here itself. */
+/** Where a pad's seed lives: `seed` mints every share of a pad here itself. */
 export const DEAD_ADDRESS: Address = "0x000000000000000000000000000000000000dEaD";
 /** The manager's `MIN_SHARES`: the seed mints this much to 0xdead on every pool, the rest to the seeder — or, on a pad, to 0xdead too. */
 export const F_MIN_SHARES = 1000n;
@@ -1201,13 +1201,13 @@ export function fPoolLaunchCalls(
   if (!a.initialized) calls.push(enc("initialize", [key]));
   calls.push(enc("seed", [poolId, a.L0, companions[1]!, a.Q0]));
   // gen 0 by construction: a launch is the pool's FIRST seed — a relaunch is `fPoolRelaunch`.
-  // No transfer to 0xdead: on a pad `seed` mints every share there itself (decisions 036).
+  // No transfer to 0xdead: on a pad `seed` mints every share there itself.
   if (a.openBuy) {
     const j = bases.indexOf(a.bases[a.openBuy.j]!);
     if (j < 0) throw new Error(`logswap: openBuy.j = ${a.openBuy.j} is not a leg`);
     calls.push(enc("swapQuoteIn", [poolId, BigInt(j), a.openBuy.amountIn, a.openBuy.minOut ?? 0n, a.account]));
   }
-  // the name, the desk's gates and its list are the POLICY's (decisions 044, 049), not the
+  // the name, the desk's gates and its list are the POLICY's, not the
   // manager's: they cannot ride in this batch — `fPoolLaunch` and `fPoolDeskOpening` send them
   // right after, as the same creator
   calls.push(...(a.extra ?? []));
@@ -1215,8 +1215,8 @@ export function fPoolLaunchCalls(
 }
 
 /**
- * The desk's opening posture, on its policy (decisions 044, 048): gated minting, the creator a
- * minter. No appointment: the authority is the operator until one is appointed (decisions 037).
+ * The desk's opening posture, on its policy: gated minting, the creator a
+ * minter. No appointment: the authority is the operator until one is appointed.
  * Two writes to `PrivatePolicy`; the launch batch cannot carry them (they are not manager calls).
  */
 export async function fPoolDeskOpening(c: LogswapClient, a: { poolId: Hex; account: Address; policy?: Address }): Promise<Hash[]> {
@@ -1256,7 +1256,7 @@ export async function fPoolLaunch(
   return { hash, poolId };
 }
 
-// ─── the roles, on the policy (decisions 044) ─────────────────────────────────────────────
+// ─── the roles, on the policy ─────────────────────────────────────────────
 //
 // Every write here goes to the pool's POLICY, not the manager: the manager holds no role. `policy`
 // may be passed when in hand (`FPoolState.policy`, `FPoolRoles.policy`); otherwise it is read once.
@@ -1276,7 +1276,7 @@ async function writePolicy(c: LogswapClient, abi: readonly unknown[], a: { poolI
 }
 
 /**
- * Propose the next authority — step one of two (decisions 020), on the pool's policy. Nothing moves
+ * Propose the next authority — step one of two, on the pool's policy. Nothing moves
  * until `next` accepts; proposing again (the zero address included) cancels a pending proposal.
  * Indexed on-chain via the policy's AuthorityProposed.
  */
@@ -1287,13 +1287,13 @@ export async function fPoolProposeAuthority(c: LogswapClient, a: { poolId: Hex;
 /**
  * Accept a pending proposal — step two; only the proposed address can. Indexed via the policy's
  * AuthoritySet. On the desk's policy this clears the operator (pending and accepted) and voids the
- * seller's list (decisions 040, 044).
+ * seller's list.
  */
 export async function fPoolAcceptAuthority(c: LogswapClient, a: { poolId: Hex; account: Address; policy?: Address }) {
   return writePolicy(c, fPolicyBaseAbi, a, "acceptAuthority", []);
 }
 
-// ─── the desk's controls (PrivatePolicy; decisions 021, 044) ───────────────────────────────
+// ─── the desk's controls (PrivatePolicy) ───────────────────────────────
 
 /** Turn the mint / swap gates on or off (the authority, on the desk's policy). `burn` is never gated. */
 export async function fPoolSetGates(
@@ -1305,7 +1305,7 @@ export async function fPoolSetGates(
 
 /**
  * Add to or remove from the pool's MINTERS — who may mint, and swap (a zap in is both under one
- * lock) — in one call (the authority, on the desk's policy; decisions 048). The list is keyed by
+ * lock) — in one call (the authority, on the desk's policy). The list is keyed by
  * the authority that granted it: a handover starts the buyer with an empty one. Stamps the
  * block: no swap lands in it (047).
  */
@@ -1316,7 +1316,7 @@ export async function fPoolSetMinters(
   return writePolicy(c, privatePolicyAbi, a, "setMinters", [a.who, a.allowed]);
 }
 
-/** Add to or remove from the pool's TAKERS — who may swap only — in one call (the authority; decisions 048). Stamps the block. */
+/** Add to or remove from the pool's TAKERS — who may swap only — in one call (the authority). Stamps the block. */
 export async function fPoolSetTakers(
   c: LogswapClient,
   a: { poolId: Hex; who: readonly Address[]; allowed: boolean; account: Address; policy?: Address },
@@ -1344,13 +1344,13 @@ export async function fPoolIsAllowed(c: LogswapClient, poolId: Hex, who: Address
   return readDesk<boolean>(c, poolId, who, "isAllowed", policy);
 }
 
-/** Label the pool — the authority's own words on the pool's POLICY (decisions 049), mutable, never identity. At most 31 bytes of UTF-8. */
+/** Label the pool — the authority's own words on the pool's POLICY, mutable, never identity. At most 31 bytes of UTF-8. */
 export async function fPoolSetName(c: LogswapClient, a: { poolId: Hex; name: string; account: Address; policy?: Address }) {
   return writePolicy(c, fPolicyBaseAbi, a, "setName", [textToBytes32(a.name)]);
 }
 
 /**
- * What the PROTOCOL says an address is — "Keyrock" — on the REGISTRY (decisions 049). Only its
+ * What the PROTOCOL says an address is — "Keyrock" — on the REGISTRY. Only its
  * owner, the LOG authority, may write it, which is what makes it an attestation rather than a
  * claim anyone could make about themselves.
  */
@@ -1387,7 +1387,7 @@ async function registryAddress(c: LogswapClient): Promise<Address> {
   return registry;
 }
 
-/** Who runs the pool (decisions 037): the appointed operator, or the authority until one is. */
+/** Who runs the pool: the appointed operator, or the authority until one is. */
 export function fPoolOperatorOf(s: Pick<FPoolRoles, "authority" | "operator">): Address {
   return s.operator === ZERO_ADDRESS ? s.authority : s.operator;
 }
@@ -1408,7 +1408,7 @@ export async function fPoolAcceptOperator(c: LogswapClient, a: { poolId: Hex; ac
 
 /**
  * The next generation's composition (operator; private pools only; ONLY while the pool is
- * unseeded — between a retire and the seed that prices it, decisions 037). `weights` has one
+ * unseeded — between a retire and the seed that prices it). `weights` has one
  * entry per leg the pool has ever had, in index order (0 retires a leg; indices are never reused),
  * then one per base in `newBases`, appended; they sum to 1e18 exactly. No value moves: the
  * following {@link fPoolSeed} names every reserve. A live reshape is {@link fPoolRelaunch} with
@@ -1451,7 +1451,7 @@ export interface DiscoveredFPool {
   weights: bigint[];
   phi: bigint;
   kind: FPoolKind;
-  /** The pool's policy AT BIRTH — the contract the key names (decisions 041, 044, 045). The LIVE one is {@link getFPool}'s `policy`: the registry's owner may have moved the pool (046, `PolicyMigrated`). */
+  /** The pool's policy AT BIRTH — the contract the key names. The LIVE one is {@link getFPool}'s `policy`: the registry's owner may have moved the pool (046, `PolicyMigrated`). */
   policy: Address;
   /** Who was born holding the pool (immutable). The LIVE authority is the policy's — {@link getFPoolRoles}. */
   creator: Address;
@@ -1459,7 +1459,7 @@ export interface DiscoveredFPool {
   block: bigint;
   /** Whether `seed` has run; an unseeded pool has no floor and no float, so nothing to show. */
   seeded: boolean;
-  /** The quote the pool was born with. Zero is the launchpad's signature (launchpad.md §3). */
+  /** The quote the pool was born with. Zero is the launchpad's signature. */
   q0: bigint;
   /**
    * The PRODUCT the pool is, by the spec's definition rather than a guess: a LAUNCH is one asset
@@ -1521,13 +1521,13 @@ export async function discoverFPools(
         block: l.blockNumber ?? 0n,
         seeded: q0 !== undefined,
         q0: q0 ?? 0n,
-        shape: kind === "pad" ? "launch" : "basket", // the policy's word, not n = 1: a mono POL is a pool (decisions 036, 049)
+        shape: kind === "pad" ? "launch": "basket", // the policy's word, not n = 1: a mono POL is a pool 
       };
     }),
   );
 }
 
-// ─── the policy page: what an authority controls (decisions 044) ────────────────────────
+// ─── the policy page: what an authority controls ────────────────────────
 //
 // One policy serves every pool of its kind, so "the pools I control" is not a policy's list: it is
 // every pool whose policy answers `authority(poolId) == me`. Discovery from the log stream (or the

package/src/keys.ts

@@ -25,7 +25,7 @@ export interface PoolKey {
   /**
    * The swap fee, WAD, fixed for the life of the market: `FEE_MIN` (1 bp) ≤ φ ≤ `FEE_MAX` (25%),
    * or `0n`, which selects `DEFAULT_FEE` (2 bp) at read time. Four fields since C version 4
-   * (decisions 042): `kappa` and `alpha` left with the variance kernel, and `phiMin` — a floor with
+   *: `kappa` and `alpha` left with the variance kernel, and `phiMin` — a floor with
    * nothing above it — became `phi`. Every pool id changed with the shape.
    */
   phi: bigint;

package/src/liquidity.ts

@@ -2,7 +2,7 @@
  * liquidity.ts — providing, editing and exiting a C position.
  *
  * A class is (ξ, μ, L): floor, cap, exposure. One primitive sets all three — `update` — and every
- * edit is a constraint on it. The vocabulary follows the geometry (decisions 009): **the verb
+ * edit is a constraint on it. The vocabulary follows the geometry: **the verb
  * names the axis, the direction is a signed rung count**, and only two direction-words survive,
  * because each names a wallet flow the user must see.
  *
@@ -15,7 +15,7 @@
  *   └─ reprice(ξ')         R pinned: L' = L·e^{ξ' − ξ}, dormant only
  *   mint · burn · claim
  *
- * Every edit is ONE action of the router's batch (decisions 010, `actions.ts`), which is what
+ * Every edit is ONE action of the router's batch (`actions.ts`), which is what
  * lets it settle in kind, or in base, or in quote: `settleIn` appends the one swap that nets the
  * other side, and the batch moves a single token. `previewEdit` is the lens's `previewUpdate` —
  * the exact flows, mint fee and swept fees included — and is what an editor shows before its one
@@ -99,7 +99,7 @@ export async function mint(c: LogswapClient, a: MintArgs): Promise<Hash> {
 
 export interface CreateMarketArgs extends WriteOptions {
   key: PoolKey;
-  /** Launch log-price. Bounded by the manager to ±46 (the price domain, decisions 012). */
+  /** Launch log-price. Bounded by the manager to ±46 (the price domain). */
   x0: bigint;
   /** The backstop's floor — the first mint's rung, permanent for the pool's life. */
   targetFloor: bigint;
@@ -112,7 +112,7 @@ export interface CreateMarketArgs extends WriteOptions {
 
 /**
  * Create a market ATOMICALLY: `initialize` at `x0` plus the backstop-establishing first mint in
- * one transaction — the canonical creation path (decisions 013, security-review H-02). The
+ * one transaction — the canonical creation path. The
  * two-step path let an attacker seat the PERMANENT backstop at a hostile rung between an honest
  * `initialize` and its first mint; here either both land or neither, and a front-run of the whole
  * call reverts it without moving a wei. No cap: the first mint IS the backstop and must be
@@ -140,7 +140,7 @@ export interface ZapArgs extends WriteOptions {
   /** Fund entirely from base (true) or entirely from quote (false). */
   fundWithBase: boolean;
   amountIn: bigint;
-  /** The least the swap leg may return (contracts 7c82eed, decisions 043): the zap's own slippage bound, as `swapExactIn`'s. Required. */
+  /** The least the swap leg may return: the zap's own slippage bound, as `swapExactIn`'s. Required. */
   minSwapOut: bigint;
   targetFloor: bigint;
   cap?: bigint;
@@ -155,7 +155,7 @@ export interface ZapArgs extends WriteOptions {
  *
  * Routing the imbalanced part through the CURVE is the point, not an implementation detail. A
  * pro-rata deposit of one asset would be a zero-slippage, zero-fee swap at stale spot — a subsidy
- * paid by the incumbent LPs (`logswap-docs` §*Quote-only capital*). Paying the curve removes it.
+ * paid by the incumbent LPs. Paying the curve removes it.
  */
 export async function zapIn(c: LogswapClient, a: ZapArgs): Promise<Hash> {
   return sendRouterWriteWithPermits(c, {
@@ -226,7 +226,7 @@ export interface MoveArgs extends WriteOptions {
  * Reposition at constant exposure — the L-pinned parent of `floor`, `cap` and `shift`; in kind.
  *
  * **Bound it.** The router used to settle this entry with no limit, which meant a reposition that
- * priced differently by inclusion time could pull the whole allowance (security-review2 M-01).
+ * priced differently by inclusion time could pull the whole allowance.
  * The bounds are required; {@link UNBOUNDED} is an explicit, visible opt-out.
  */
 export async function move(c: LogswapClient, a: MoveArgs): Promise<Hash> {
@@ -325,7 +325,7 @@ export async function edit(c: LogswapClient, a: EditArgs & { toFloor: bigint; to
   if (settleIn === "kind") {
     settle = settleInKind(key, recipient, { ...boundsFromFlows(p.dBase, p.dQuote, a.slippageBps), ...defined(a) });
   } else {
-    // the swept fees ride INSIDE dQuote (the manager burns by owner and nets them; decisions 018),
+    // the swept fees ride INSIDE dQuote (the manager burns by owner and nets them),
     // so quote's open delta after the update is dQuote itself — `fees` is reported for display only
     const otherFlow = settleIn === "base" ? p.dQuote : p.dBase; // + = owed, − = released
     const otherIsBase = settleIn === "quote";