@logswap/sdk 0.5.54 → 0.5.56

package/src/client.ts

@@ -24,7 +24,7 @@ export interface LogswapAddresses {
    */
   fPoolManager?: Address;
   /**
-   * The protocol's four F policies, one per kind (decisions 044): every F pool names one in its key,
+   * The protocol's four F policies, one per kind: every F pool names one in its key,
    * and the pool's roles, gates and terms live on it. A deployment predating them carries none.
    */
   publicPolicy?: Address;
@@ -32,7 +32,7 @@ export interface LogswapAddresses {
   polPolicy?: Address;
   padPolicy?: Address;
   /**
-   * The policy registry (decisions 046): what a pool of each kind may be born under, and the
+   * The policy registry: what a pool of each kind may be born under, and the
    * owner that may move a pool between policies. Read from the F manager (`registry()`) when
    * absent; a deployment with none asks nobody.
    */
@@ -69,18 +69,18 @@ export function createLogswapClient(args: {
  * 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`
+ * **3** since 2026-09-03: `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.
+ * swept fees, which is why `exit`'s settle-to-one-asset math changed with it.
  *
- * **4** since 2026-09-18 (decisions 042 + 040): `PoolKey` is `(base, quote, tickSpacing, phi)` —
+ * **4** since 2026-09-18: `PoolKey` is `(base, quote, tickSpacing, phi)` —
  * the variance kernel and its two key fields are gone, so every pool id changed; `phiEff` is
  * `phiOf`; `getPool` lost `sigma2Ema`; `Initialize` lost two fields; the cut is
  * `MINT_FEE_PROTOCOL_CUT` / `setFeeParams`.
  */
 export const EXPECTED_VERSION = 4n;
 /**
- * The F manager's own tag (contracts 25a7bcf: 5 — the key's salt, pool names, the sponsor registry;
+ * The F manager's own tag (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
@@ -92,43 +92,43 @@ export const EXPECTED_VERSION = 4n;
  */
 // 7 (2026-09-15): the reserves are the state and the marks derived, `lockStrike`, the dividend
 // harvest, the relaunch (`dissolve(poolId, successor)`, `rollIn`), the reserve-named seed, the
-// sponsor facet — decisions 025–031.
-// 8 (2026-09-15): the relaunch is in place (decisions 032) — every share id carries the
+// sponsor facet.
+// 8 (2026-09-15): the relaunch is in place — every share id carries the
 // generation (`fPoolShareId(poolId, gen)`), `dissolve(poolId)`, `redeem`, `claim` / `dividendOf`
 // / `rollIn` / `previewRollIn` take the generation, `Pool.gen` replaces `dissolved` and
 // `successor`. A 7 deployment's share ids do not even resolve with this SDK.
-// 9 (2026-09-16): `deepen` is gone, `Pool.leverTheta` is `harvestedTheta` (decisions 034).
+// 9 (2026-09-16): `deepen` is gone, `Pool.leverTheta` is `harvestedTheta`.
 // 10 (2026-09-17): no floor guard — `Pool.minBuffer`, `raiseMinBuffer`, `LEVER_FLOOR` gone;
-// `dissolve` needs an empty bid on every pool (decisions 035); the key bit is the CLASS, `pad`
+// `dissolve` needs an empty bid on every pool; the key bit is the CLASS, `pad`
 // (036): `seed` mints a pad's shares to 0xdead, and the operator, the gates and the list are
 // refused on it — `fPoolLaunch` no longer transfers the seed itself.
-// 11 (2026-09-17): roles and entries (decisions 037) — the operator runs the pool (`harvest`,
+// 11 (2026-09-17): roles and entries — the operator runs the pool (`harvest`,
 // `dissolve`, `setLegs`) and is the authority until appointed, two-step (`acceptOperator`,
 // `Pool.pendingOperator`); `setLegL`/`admitLeg` are gone, `setLegs` edits the next generation's
 // table while unseeded; `fPoolRelaunch` takes `legs`.
 // `getPool` decodes one field fewer, so a 9 deployment's struct no longer matches this SDK.
-// 12 (2026-09-17): one contract (decisions 039) — the sponsor facet is folded back into the
+// 12 (2026-09-17): one contract — the sponsor facet is folded back into the
 // manager; `sponsor()` and the fallback are gone, every entry, error and event unchanged, so
 // `fPoolManagerAbi` is the manager's own ABI and no longer a union. Layout unchanged.
-// 13 (2026-09-18): one vocabulary (decisions 040) — `HARVEST_FEE` is `HARVEST_PROTOCOL_CUT` (a
+// 13 (2026-09-18): one vocabulary — `HARVEST_FEE` is `HARVEST_PROTOCOL_CUT` (a
 // cut of harvested income, not a fee on the harvest) and the exemption is `harvestCutExempt` /
 // `setHarvestCutExempt`; `acceptAuthority` clears the operator, pending and accepted (a mandate
 // is voided by the handover of the role that granted it); `setLegs` needs a generation to have
 // lived (`gen > 0`); `initialize` refuses a codeless base and `mint` refuses `to = address(0)`
 // on both managers. Layout unchanged.
-// 14 (2026-09-20): the policy (decisions 041) — `FPoolKey.policy`, every pool id moves; `dissolve` is
+// 14 (2026-09-20): the policy — `FPoolKey.policy`, every pool id moves; `dissolve` is
 // `retire`, `regenerate` releases the dead shares' pot, `harvestable`/`unharvested` are the
 // readouts; `feePerL`, `edgePerL`, `HARVEST_PROTOCOL_CUT`, `harvestCutExempt` are gone.
-// 15 (2026-09-20): the policy answers every question (decisions 044) — `FPoolKey.authority` is
+// 15 (2026-09-20): the policy answers every question — `FPoolKey.authority` is
 // `creator` (every pool id moves again); the roles, gates and list are the pool's POLICY's
 // (`FPolicyBase` / `PrivatePolicy`), not the manager's: `getPool` has `policy` and `asks` and no
 // role; `proposeAuthority`, `appointOperator`, `setGates`, `setAllowed` (`setMinters` / `setTakers` since 17) are policy writes;
 // `policyApproved(kind, policy)` / `setPolicyApproved(kind, policy, ok)`; `Regenerated` names the payee;
 // `HARVEST_CUT_MAX` / `POT_CUT_MAX` cap what a policy may route to the protocol.
-// 16 (2026-09-21): the word is POLICY (decisions 045) — a rename, no pool id moves: `FPoolKey.policy`,
+// 16 (2026-09-21): the word is POLICY — a rename, no pool id moves: `FPoolKey.policy`,
 // `IFPolicy`, `FPolicyBase`, `PublicPolicy` … `PadPolicy`, `policyApproved` / `setPolicyApproved`,
 // `PolicyApproved`; `PolPolicy.setPolicy` / `PolicySet` are `setRules` / `RulesSet`.
-// 17 (2026-09-21): the registry, the move, the stamp, two lists, one base (decisions 046–048) — no
+// 17 (2026-09-21): the registry, the move, the stamp, two lists, one base — no
 // pool id moves: the F manager takes a `PolicyRegistry` at construction and asks it at a birth
 // (`policyApproved` / `setPolicyApproved` left the manager: `registryApprove` …); the key's policy
 // is the policy at birth, `migrate` moves a pool for the registry's owner; `stamp` / `setAsks` are
@@ -149,7 +149,7 @@ export async function assertVersion(c: LogswapClient, expected = EXPECTED_VERSIO
         `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
+  // the F manager carries its own tag; assert it the same way when deployed
   if (c.addresses.fPoolManager) {
     const { fPoolManagerAbi } = await import("./generated.js");
     const gotF = await c.public.readContract({

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'.
  */
@@ -53,7 +53,7 @@ import { 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({
@@ -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;