@logswap/sdk 0.5.44 → 0.5.46

package/src/fpool.ts

@@ -12,10 +12,17 @@
  * key is variable-length and only ever partially needed (no swap path is O(n)), so it is stored
  * once at `initialize` and every later call names `(poolId, j)`. Callers hold a `bytes32`.
  *
- * **Two products, one contract.** The basket (n > 1, public authority) and the launch (n = 1, the
- * creator alone on the lever) are the same bytecode under different settings — what separates them
- * is who holds `authority` and how many bases there are, and nothing in the maths. `describeFPool`
- * below reports which shape a given pool is, because a UI has to decide what to render.
+ * **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 HOOK (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
+ * which shape a given pool is, because a UI has to decide what to render.
+ *
+ * **The roles are the hook's, not the manager's** (F version 15). The manager holds no
+ * authority, operator, gate or list: it asks the pool's hook `may(who, action)` and acts on the
+ * answer. So `getFPool` carries the hook and what it declared, {@link getFPoolRoles} reads the
+ * roles FROM the hook, and every role write — the handover, the operator, the gates, the list —
+ * is a write to the hook ({@link fPoolProposeAuthority}, {@link fPoolSetGates}, …).
  *
  * **Zaps live on the ROUTER, not here.** Permit2 is AllowanceTransfer mode, whose standing
  * allowance is keyed by spender, so a second router would cost the user an allowance per token
@@ -24,21 +31,31 @@
  */
 
 import { encodeFunctionData, toFunctionSelector, type Address, type Hash, type Hex } from "viem";
-import { fPoolManagerAbi, logswapRouterAbi } from "./generated.js";
+import { fPoolManagerAbi, logswapRouterAbi, padHookAbi, polHookAbi, privateHookAbi, publicHookAbi } from "./generated.js";
 
 /**
- * One contract, one ABI (decisions 039, F version 12): the sponsor surface — `harvest`, `claim`,
- * `dissolve`, the handover, the gates, the operator, `setLegs`, the names, the fee parameters —
- * is `FPoolManager`'s own code again. From 031 to 038 it was a delegatecall facet
- * (`FPoolSponsor`) and this ABI was the union of the two compiled halves; the union is gone with
- * the facet, and the generated ABI is the whole surface.
+ * One contract, one ABI (decisions 039, F version 12): `harvest`, `claim`, `retire`, `regenerate`,
+ * `setLegs`, the names, the fee parameters are `FPoolManager`'s own code. The roles left it for
+ * the hooks in F version 15 (decisions 044): {@link fHookBaseAbi} is what every hook shares,
+ * {@link privateHookAbi} the desk's, {@link padHookAbi} / {@link polHookAbi} / {@link publicHookAbi}
+ * the kinds'.
+ */
+export { fPoolManagerAbi, padHookAbi, polHookAbi, privateHookAbi, publicHookAbi };
+/**
+ * What every protocol hook shares (`FHookBase`): the roles and their handover, `harvestCut`,
+ * `maxHarvest`. `polHookAbi` is a superset of it and carries nothing that collides, so it stands
+ * in for the base — a call through it to any of the four hooks decodes the base's functions.
  */
-export { fPoolManagerAbi };
+export const fHookBaseAbi = polHookAbi;
 import type { LogswapClient } from "./client.js";
 
 const WAD = 10n ** 18n;
 const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000" as const;
 
+/** The optional questions a hook declared at birth (decisions 044), as bits of `Pool.asks`. */
+export const ASK_SWAP = 1;
+export const ASK_MINT = 2;
+
 /** Everything scalar about a basket pool, in one round trip's worth of reads. */
 export interface FPoolState {
   /** The pool's id — the hash of its key. There is no per-pool address. */
@@ -63,32 +80,25 @@ export interface FPoolState {
   compositeX: bigint;
   /** Σ = ∫ Σ_j w_j (dx_j)², accrued even though the fee is fixed — the kernel stays calculable. */
   bigSigma: bigint;
-  /** The cold key (decisions 037): seeds the pool, hands it over, names it, gates it (private). A creator, a treasury, a governance contract. */
-  authority: Address;
-  /** The proposed next authority, until it accepts — zero when nothing is pending (decisions 020). */
-  pendingAuthority: Address;
   /**
-   * The hot key that RUNS the pool (decisions 037): `harvest`, `dissolve`, `setLegs`. Zero means
-   * the authority itself — see {@link fPoolOperatorOf}. Appointed two-step on a private pool.
+   * The pool's policy (decisions 041, 044): 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 fPoolHookFor}) on every protocol pool.
    */
-  operator: Address;
-  /** The proposed next operator, until it accepts — zero when nothing is pending. */
-  pendingOperator: Address;
+  hook: Address;
+  /** Whether the hook asked to be consulted on swaps ({@link ASK_SWAP}) and mints ({@link ASK_MINT}) — the desk's hook does, no other. */
+  asks: number;
   /** The sponsor's own label for this pool, mutable and never identity. "" when unnamed. */
   name: string;
-  /** Only `allowed` accounts may receive minted shares. */
-  gateMint: boolean;
-  /** Only `allowed` takers may swap. */
-  gateSwap: boolean;
   /** The block of the last harvest / composition action: no swap runs in it. */
   restructureBlock: number;
   /** The rung — see {@link FPoolKind}. */
   kind: FPoolKind;
-  /** False before the first seed — and between a dissolve and the next one (decisions 032). */
+  /** False before the first seed — and between a retire and the next one (decisions 032). */
   seeded: boolean;
   /**
-   * The live GENERATION (decisions 032). Every dissolve retires one into a frozen bundle its
-   * shares redeem ({@link fPoolRedeem}) and opens the next; the share id carries it
+   * The live GENERATION (decisions 032). 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;
@@ -110,28 +120,22 @@ export async function getFPool(c: LogswapClient, poolId: Hex): Promise<FPoolStat
     } as never) as Promise<T>;
 
   // `getPool` returns the whole scalar struct in one call — the singleton's shape makes what used
-  // to be a dozen getters a single read.
+  // to be a dozen getters a single read. No role in it since F version 15: those are the hook's.
   const p = await rd<{
     quote: Address;
     phi: bigint;
-    authority: Address;
+    hook: Address;
     kind: number;
     seeded: boolean;
     gen: number;
     n: number;
     restructureBlock: number;
-    gateMint: boolean;
-    gateSwap: boolean;
+    asks: number;
     Q: bigint;
+    bigSigma: bigint;
     L: bigint;
     shares: bigint;
     theta0: bigint;
-    bigSigma: bigint;
-    harvestedTheta: bigint;
-    pendingAuthority: Address;
-    operator: Address;
-    pendingOperator: Address;
-    incomeTaken: bigint;
     name: Hex;
   }>("getPool", [poolId]);
 
@@ -156,7 +160,7 @@ export async function getFPool(c: LogswapClient, poolId: Hex): Promise<FPoolStat
   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 reserves = legs.map((l) => l[3]); // the state
-  const { quote, Q, L, phi, theta0, bigSigma, authority, pendingAuthority, operator, pendingOperator, gateMint, gateSwap, restructureBlock, seeded, gen } = p;
+  const { quote, Q, L, phi, theta0, bigSigma, hook, restructureBlock, seeded, gen } = p;
   const totalSupply = p.shares;
 
   return {
@@ -172,13 +176,9 @@ export async function getFPool(c: LogswapClient, poolId: Hex): Promise<FPoolStat
     theta,
     compositeX,
     bigSigma,
-    authority,
-    pendingAuthority,
-    operator,
-    pendingOperator,
+    hook,
+    asks: Number(p.asks),
     name: bytes32ToText(p.name),
-    gateMint,
-    gateSwap,
     restructureBlock: Number(restructureBlock),
     kind: fPoolKindOf(p.kind),
     seeded,
@@ -189,14 +189,14 @@ export async function getFPool(c: LogswapClient, poolId: Hex): Promise<FPoolStat
 }
 
 /**
- * The kind of pool (decisions 036, 038). `public`: the protocol's own pool — born with the fee
- * collector as its authority (which may hand it to a governance contract); no gates, no operator.
- * `private`, the desk: every entry — gates, a list, an operator that reshapes the legs between
- * generations, an unbounded harvest, the seed kept. `pol`, a treasury's pool or a basket: no
- * gates, no operator — composition and access fixed at birth; harvest unbounded, seed the
- * seeder's. `pad`, a launch: a POL whose harvest never lifts the floor above the seed floor and
- * whose seed the contract minted to 0xdead — one asset, open to all. private → pol → pad is the
- * ladder of rigidity; public is a pol held by the protocol.
+ * The kind of pool (decisions 036, 038, 044) — what the manager promises structurally, whatever
+ * the pool's hook answers. `public`: the protocol's own pool — its hook requires the collector as
+ * creator; no gate, no operator. `private`, the desk: the one kind whose hook may gate swaps and
+ * mints, with an operator that reshapes the legs between generations. `pol`, a treasury's pool
+ * or a basket: composition and access fixed at birth. `pad`, a launch: a POL whose harvest is
+ * income only whatever its hook says and whose seed the contract minted to 0xdead — one asset,
+ * open to all. private → pol → pad is the ladder of rigidity; public is a pol held by the
+ * protocol. Every rate, role and gate is the hook's.
  */
 export type FPoolKind = "public" | "private" | "pol" | "pad";
 /** The key's enum values. */
@@ -208,40 +208,110 @@ export function fPoolKindOf(n: number | bigint): FPoolKind {
   return k;
 }
 
+/** The deployment's hook for a kind (decisions 044): what a key of that kind names. */
+export function fPoolHookFor(c: LogswapClient, kind: FPoolKind): Address {
+  const a = c.addresses;
+  const hook = kind === "public" ? a.publicHook : kind === "private" ? a.privateHook : kind === "pol" ? a.polHook : a.padHook;
+  if (!hook) throw new Error(`logswap: this deployment carries no ${kind} hook`);
+  return hook;
+}
+
+/** The hook a pool named in its key — one read; {@link getFPool} carries it too. */
+export async function fPoolHookOf(c: LogswapClient, poolId: Hex): Promise<Address> {
+  const p = (await c.public.readContract({
+    address: c.addresses.fPoolManager!,
+    abi: fPoolManagerAbi,
+    functionName: "getPool",
+    args: [poolId],
+  } as never)) as { quote: Address; hook: Address };
+  if (/^0x0{40}$/i.test(p.quote)) throw new Error(`logswap: no F pool with id ${poolId}`);
+  return p.hook;
+}
+
+/**
+ * A pool's roles, as its HOOK holds them (decisions 044). `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
+ * operator and no gate: those fields read zero / false.
+ */
+export interface FPoolRoles {
+  hook: Address;
+  creator: Address;
+  authority: Address;
+  /** The proposed next authority, until it accepts — zero when nothing is pending (decisions 020). */
+  pendingAuthority: Address;
+  operator: Address;
+  pendingOperator: Address;
+  gateMint: boolean;
+  gateSwap: boolean;
+  /** The hook's own ceiling on a harvest now — the manager's `harvestable` narrowed by the hook's rule. */
+  maxHarvest: bigint;
+}
+
+/** Read a pool's roles from its hook. `state` saves the `getPool` round trip when already in hand. */
+export async function getFPoolRoles(c: LogswapClient, poolId: Hex, state?: Pick<FPoolState, "hook" | "kind">): Promise<FPoolRoles> {
+  const s = state ?? (await getFPool(c, poolId));
+  const rdHook = <T>(abi: readonly unknown[], functionName: string) =>
+    c.public.readContract({ address: s.hook, abi, functionName, args: [poolId] } as never) as Promise<T>;
+  const [creator, authority, pendingAuthority, maxHarvest] = await Promise.all([
+    rdHook<Address>(fHookBaseAbi, "creator"),
+    rdHook<Address>(fHookBaseAbi, "authority"),
+    rdHook<Address>(fHookBaseAbi, "pendingAuthority"),
+    rdHook<bigint>(fHookBaseAbi, "maxHarvest"),
+  ]);
+  const desk = s.kind === "private";
+  const [operator, pendingOperator, gateMint, gateSwap] = desk
+    ? await Promise.all([
+        rdHook<Address>(privateHookAbi, "operator"),
+        rdHook<Address>(privateHookAbi, "pendingOperator"),
+        rdHook<boolean>(privateHookAbi, "gateMint"),
+        rdHook<boolean>(privateHookAbi, "gateSwap"),
+      ])
+    : [ZERO_ADDRESS, ZERO_ADDRESS, false, false];
+  return { hook: s.hook, creator, authority, pendingAuthority, operator, pendingOperator, gateMint, gateSwap, maxHarvest };
+}
+
 /** Which of the two products a pool is configured as — a pad is a launch, anything else a basket/pool. A UI has to choose what to render. */
 export type FPoolShape = "launch" | "basket";
 
 export interface FPoolDescription {
   shape: FPoolShape;
-  /** n = 1 with a private authority is the launch shape (f-pool §6.5). */
+  /** The pad is the launch shape, by the kind (decisions 036). */
   legs: number;
   /** True when the pool holds no quote: an all-base resting ask. base→quote is the one blocked path. */
   atFloor: boolean;
-  /** Fee income earned per unit L so far, `θ₀ − θ` with the lever's displacement backed out. */
-  feePerL: bigint;
-  /** The model-free LP edge, `F − ½Σ`. Exact at any n: V is separable in the logs. */
-  edgePerL: bigint;
+  /**
+   * This generation's fee income still in the pool, quote: `L·(θ₀ − θ)` (F version 14 —
+   * `feePerL` before, per unit L). A harvest of capital moves the reference floor, so this counts
+   * from the first wei after it.
+   */
+  unharvested: bigint;
+  /** The most a harvest may take now by the KIND's promise: the bid, and on a pad the income. The hook 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). */
+  pot: bigint;
 }
 
 export async function describeFPool(c: LogswapClient, s: FPoolState): Promise<FPoolDescription> {
-  const rd = <T>(functionName: string) =>
+  const rd = <T>(functionName: string, args: readonly unknown[] = [s.poolId]) =>
     c.public.readContract({
       address: c.addresses.fPoolManager!,
       abi: fPoolManagerAbi,
       functionName,
-      args: [s.poolId],
+      args,
     } as never) as Promise<T>;
-  // an unseeded pool has no L: nothing earned, and θ (hence feePerL, hence edgePerL) is not
-  // defined at L = 0. Older deployments revert with DivWadFailed rather than answering zero.
-  const [feePerL, edgePerL] = s.L > 0n
-    ? await Promise.all([rd<bigint>("feePerL"), rd<bigint>("edgePerL")])
-    : [0n, 0n];
+  // an unseeded pool has no L: nothing earned, nothing to harvest, no pot
+  const [unharvested, harvestable, pot] = s.L > 0n
+    ? 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)
     legs: s.bases.length,
     atFloor: s.Q === 0n,
-    feePerL,
-    edgePerL,
+    unharvested,
+    harvestable,
+    pot,
   };
 }
 
@@ -798,7 +868,14 @@ export interface FPoolCreateArgs {
   phi: bigint;
   /** The rung (decisions 036) — see {@link FPoolKind}. In the key: the pool's identity, never changed after. */
   kind: FPoolKind;
-  authority: Address;
+  /**
+   * The pool's policy (decisions 041, 044): the contract the key names, approved by the protocol
+   * for the kind. Defaults to the deployment's hook for `kind` ({@link fPoolHookFor}) — the one
+   * every protocol pool names.
+   */
+  hook?: Address;
+  /** Who is born holding the pool: immutable identity, the pool's first authority (the hook records it). */
+  creator: Address;
   /**
    * The differentiator, and nothing else. Identity is the key's hash, so one sponsor cannot run
    * two pools of the same shape without varying it — the second `initialize` would land on the
@@ -832,12 +909,26 @@ export function sortFPoolLegs<T>(bases: Address[], ...companions: T[][]): { base
   return { bases: idx.map((i) => bases[i]!), companions: companions.map((arr) => idx.map((i) => arr[i]!)) };
 }
 
+/** The key as the manager hashes it: legs sorted, the kind's hook filled in when none is named. */
+export function fPoolKeyOf(c: LogswapClient, a: Omit<FPoolCreateArgs, "account">) {
+  const { bases, companions } = sortFPoolLegs(a.bases, a.weights);
+  return {
+    quote: a.quote,
+    bases,
+    weights: companions[0]!,
+    phi: a.phi,
+    kind: F_KIND[a.kind],
+    hook: a.hook ?? fPoolHookFor(c, a.kind),
+    creator: a.creator,
+    salt: a.salt ?? ZERO_SALT,
+  };
+}
+
 /** Create the pool (no funds move — `seed` arms it). Returns the tx hash; read the id with `fPoolIdOf`. */
 export async function fPoolInitialize(c: LogswapClient, a: FPoolCreateArgs) {
   const sum = a.weights.reduce((x, y) => x + y, 0n);
   if (sum !== 10n ** 18n) throw new Error(`logswap: weights sum to ${sum}, expected 1e18`);
-  const { bases, companions } = sortFPoolLegs(a.bases, a.weights);
-  const key = { quote: a.quote, bases, weights: companions[0]!, phi: a.phi, kind: F_KIND[a.kind], authority: a.authority, salt: a.salt ?? ZERO_SALT };
+  const key = fPoolKeyOf(c, a);
   const wallet = requireWallet(c);
   const { request } = await c.public.simulateContract({
     address: c.addresses.fPoolManager!,
@@ -851,8 +942,7 @@ export async function fPoolInitialize(c: LogswapClient, a: FPoolCreateArgs) {
 
 /** The pool id is the key's hash — pure, so it can be read before or after creation. */
 export async function fPoolIdOf(c: LogswapClient, a: Omit<FPoolCreateArgs, "account">): Promise<Hex> {
-  const { bases, companions } = sortFPoolLegs(a.bases, a.weights);
-  const key = { quote: a.quote, bases, weights: companions[0]!, phi: a.phi, kind: F_KIND[a.kind], authority: a.authority, salt: a.salt ?? ZERO_SALT };
+  const key = fPoolKeyOf(c, a);
   return c.public.readContract({
     address: c.addresses.fPoolManager!,
     abi: fPoolManagerAbi,
@@ -889,82 +979,72 @@ export async function fPoolSeed(
 }
 
 /**
- * Retire the live generation (decisions 025, 032, 035) — the raw entry. Allowed only at an empty
- * bid, Q ≤ L/1e9, on every pool: the market took it, or the authority 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}) or rolls ({@link fPoolRollIn}),
- * forever; the pool is unseeded until the next {@link fPoolSeed}, which opens generation
- * `gen + 1` under the same id, gates and lists.
+ * Retire the live generation (decisions 025, 032, 035) — 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})
+ * or rolls ({@link fPoolRollIn}), forever; the pool is unseeded until the next {@link fPoolSeed},
+ * which opens generation `gen + 1` under the same id, hook, roles, gates and lists.
  */
-export async function fPoolDissolve(c: LogswapClient, a: { poolId: Hex; account: Address }) {
-  return writeFPool(c, a.poolId, "dissolve", [], a.account);
+export async function fPoolRetireRaw(c: LogswapClient, a: { poolId: Hex; account: Address }) {
+  return writeFPool(c, a.poolId, "retire", [], a.account);
 }
 
 /**
- * Retire the live generation as ONE transaction: the harvests that empty the bid
+ * Retire the live generation as ONE transaction: the harvest that empties the bid
  * ({@link fPoolEmptyingHarvests} — a dividend to every share; none when it is already empty),
- * then `dissolve` — the manager's `multicall`, the authority as sender. What a sponsor's
- * "dissolve" button should call. Throws before sending on a pad that still bids.
+ * then `retire` — the manager's `multicall`, the operator as sender. What a sponsor's
+ * "retire" button should call. Throws before sending on a pad that still bids.
  */
 export async function fPoolRetire(c: LogswapClient, a: { poolId: Hex; account: Address }) {
   const harvests = await fPoolEmptyingHarvests(c, a.poolId);
-  if (harvests.length === 0) return fPoolDissolve(c, a);
+  if (harvests.length === 0) return fPoolRetireRaw(c, a);
   const enc = (functionName: string, args: unknown[]) =>
     encodeFunctionData({ abi: fPoolManagerAbi, functionName, args } as never) as Hex;
-  const calls: Hex[] = [...harvests.map((amount) => enc("harvest", [a.poolId, amount, a.account])), enc("dissolve", [a.poolId])];
+  const calls: Hex[] = [...harvests.map((amount) => enc("harvest", [a.poolId, amount, a.account])), enc("retire", [a.poolId])];
   return writeFPool0(c, "multicall", [calls], a.account);
 }
 
 /**
  * The harvests that empty an unlocked pool's bid, in order — what a relaunch sends before its
- * `dissolve` (decisions 035: a dissolve needs an empty bid on every pool). One `harvest(Q)` when a
- * collector is set. With none, the cut on income STAYS in the pool as LP quote (decisions 002)
- * and reads as taken income, so a second harvest — capital, no cut — takes the rest; the
- * contract's own arithmetic, replayed. `[]` when the bid is already empty. Throws on a
- * pad that still bids (its bid empties only as the market sells it down), and in
- * the one shape two harvests cannot empty (no collector, income above Q — harvest by hand).
+ * `retire` (decisions 035: 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 hook keeps a floor on the bid
+ * (`PolHook.keepQuote`, decisions 044): a `retire` under that hook waits for the market.
  */
 export async function fPoolEmptyingHarvests(c: LogswapClient, poolId: Hex): Promise<bigint[]> {
-  const rd = <T>(functionName: string, args: readonly unknown[] = []) =>
-    c.public.readContract({ address: c.addresses.fPoolManager!, abi: fPoolManagerAbi, functionName, args } as never) as Promise<T>;
-  const [p, feePerL, fee, exempt, collector] = await Promise.all([
-    rd<{ Q: bigint; L: bigint; kind: number; incomeTaken: bigint }>("getPool", [poolId]),
-    rd<bigint>("feePerL", [poolId]),
-    rd<bigint>("HARVEST_PROTOCOL_CUT"),
-    rd<boolean>("harvestCutExempt", [poolId]),
-    rd<Address>("feeCollector"),
-  ]);
-  if (p.Q === 0n) return [];
-  if (p.kind === F_KIND.pad) throw new Error("logswap: a pad is retired only once its bid is empty (decisions 035)");
-  const earned = feePerL > 0n ? (feePerL * p.L) / WAD : 0n;
-  let taken = p.incomeTaken;
-  let q = p.Q;
-  const amounts: bigint[] = [];
-  for (let i = 0; i < 2 && q > 0n; i++) {
-    const amount = q;
-    const left = earned > taken ? earned - taken : 0n;
-    const taxable = amount < left ? amount : left;
-    taken += taxable;
-    const pFee = exempt ? 0n : (taxable * fee) / WAD;
-    const leaving = pFee !== 0n && collector !== ZERO_ADDRESS ? amount : amount - pFee;
-    q -= leaving;
-    amounts.push(amount);
-  }
-  if (q > 0n) throw new Error("logswap: the bid does not empty in two harvests (no collector, income above Q) — harvest by hand first");
-  return amounts;
+  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)");
+  const { maxHarvest } = await getFPoolRoles(c, poolId, s);
+  if (maxHarvest < s.Q) throw new Error("logswap: the pool's hook keeps a floor on the bid — it cannot be harvested empty (decisions 044)");
+  return [s.Q];
+}
+
+/**
+ * Release the dead shares' pot under the hook's terms (decisions 041, 044) — a pad's graduation.
+ * The manager harvests the generation's income first (the pot then holds everything the dead
+ * shares earned), asks the hook, 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
+ * float the pool owns, a slice of every reserve burned. The hook refuses under its rung's
+ * threshold (`PadHook.NotGraduated`). Whoever runs the pool.
+ */
+export async function fPoolRegenerate(c: LogswapClient, a: { poolId: Hex; to?: Address; account: Address }) {
+  return writeFPool(c, a.poolId, "regenerate", [a.to ?? a.account], a.account);
 }
 
 /**
  * The relaunch as ONE transaction (decisions 025, 032, 035, 037): `harvest` the bid out — a
- * dividend to every share, {@link fPoolEmptyingHarvests} — `dissolve` the live generation at the
+ * 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
  * `seed` it with what came back — the manager's `multicall`, one sender throughout, the same
  * pool. The operator's when one is appointed and the seed's inventory is its own; by default the
- * authority's. Gates, allowlist and names carry over; anything else goes in `extra`, pre-encoded
- * against {@link fPoolManagerAbi}. The seed names reserves (decisions 029): `r0` outright — one
- * per leg of the NEXT table, 0 for a retired leg — or `x0` marks against the next table's
- * `weights`.
+ * authority's. The hook, its roles, gates, allowlist and the name carry over; anything else goes
+ * in `extra`, pre-encoded against {@link fPoolManagerAbi}. The seed names reserves (decisions
+ * 029): `r0` outright — one per leg of the NEXT table, 0 for a retired leg — or `x0` marks
+ * against the next table's `weights`.
  */
 export async function fPoolRelaunch(
   c: LogswapClient,
@@ -986,7 +1066,7 @@ export async function fPoolRelaunch(
     encodeFunctionData({ abi: fPoolManagerAbi, functionName, args } as never) as Hex;
   const calls: Hex[] = [
     ...harvests.map((amount) => enc("harvest", [a.poolId, amount, a.account])),
-    enc("dissolve", [a.poolId]),
+    enc("retire", [a.poolId]),
     ...(a.shares > 0n ? [enc("redeem", [a.poolId, BigInt(gen), a.account, a.shares])] : []),
     ...(a.legs ? [enc("setLegs", [a.poolId, a.legs.weights, a.legs.newBases ?? []])] : []),
     enc("seed", [a.poolId, a.L0, r0, a.Q0]),
@@ -1040,7 +1120,8 @@ export function fPoolLaunchCalls(
   const given = "r0" in a ? a.r0 : a.x0.map((x, j) => fPoolReserveAt((a.weights[j]! * a.L0) / WAD, x));
   if (given.length !== a.bases.length) throw new Error(`logswap: ${given.length} reserves for ${a.bases.length} legs`);
   const { bases, companions } = sortFPoolLegs(a.bases, a.weights, given);
-  const key = { quote: a.quote, bases, weights: companions[0]!, phi: a.phi, kind: F_KIND[a.kind], authority: a.authority, salt: a.salt ?? ZERO_SALT };
+  if (!a.hook) throw new Error("logswap: fPoolLaunchCalls needs the key's hook — fPoolLaunch fills it from the deployment");
+  const key = { quote: a.quote, bases, weights: companions[0]!, phi: a.phi, kind: F_KIND[a.kind], hook: a.hook, creator: a.creator, salt: a.salt ?? ZERO_SALT };
   const enc = (functionName: string, args: unknown[]) =>
     encodeFunctionData({ abi: fPoolManagerAbi, functionName, args } as never) as Hex;
   const calls: Hex[] = [];
@@ -1054,16 +1135,25 @@ export function fPoolLaunchCalls(
     calls.push(enc("swapQuoteIn", [poolId, BigInt(j), a.openBuy.amountIn, a.openBuy.minOut ?? 0n, a.account]));
   }
   if (a.name) calls.push(enc("setName", [poolId, textToBytes32(a.name)]));
-  if (a.kind === "private") {
-    // the desk's opening posture: gated minting, the creator listed. No appointment: the
-    // authority is the operator until one is appointed (decisions 037)
-    calls.push(enc("setGates", [poolId, true, false]));
-    calls.push(enc("setAllowed", [poolId, [a.account], true]));
-  }
+  // the desk's gates and list are the HOOK's (decisions 044), not the manager's: they cannot ride
+  // in this batch — `fPoolDeskOpening` sends them right after, as the same creator
   calls.push(...(a.extra ?? []));
   return calls;
 }
 
+/**
+ * The desk's opening posture, on its hook (decisions 044): gated minting, the creator listed. No
+ * appointment: the authority is the operator until one is appointed (decisions 037). Two writes
+ * to `PrivateHook`; the launch batch cannot carry them (they are not manager calls).
+ */
+export async function fPoolDeskOpening(c: LogswapClient, a: { poolId: Hex; account: Address; hook?: Address }): Promise<Hash[]> {
+  const hook = a.hook ?? fPoolHookFor(c, "private");
+  return [
+    await fPoolSetGates(c, { poolId: a.poolId, gateMint: true, gateSwap: false, account: a.account, hook }),
+    await fPoolSetAllowed(c, { poolId: a.poolId, who: [a.account], allowed: true, account: a.account, hook }),
+  ];
+}
+
 /**
  * Create a pool as ONE transaction: `initialize`, `seed`, the seed lock, the opening buy, the
  * name, the private-pool gates — the manager's `multicall`, the creator as sender throughout.
@@ -1086,48 +1176,76 @@ export async function fPoolLaunch(
   a: FPoolLaunchArgs & ({ r0: bigint[] } | { x0: bigint[] }),
 ): Promise<{ hash: Hash; poolId: Hex }> {
   const poolId = await fPoolIdOf(c, a);
-  const hash = await writeFPool0(c, "multicall", [fPoolLaunchCalls(poolId, a)], a.account);
+  const calls = fPoolLaunchCalls(poolId, { ...a, hook: a.hook ?? fPoolHookFor(c, a.kind) });
+  const hash = await writeFPool0(c, "multicall", [calls], a.account);
   return { hash, poolId };
 }
 
+// ─── the roles, on the hook (decisions 044) ─────────────────────────────────────────────
+//
+// Every write here goes to the pool's HOOK, not the manager: the manager holds no role. `hook`
+// may be passed when in hand (`FPoolState.hook`, `FPoolRoles.hook`); otherwise it is read once.
+
+/** A write keyed by poolId, on the pool's hook. */
+async function writeHook(c: LogswapClient, abi: readonly unknown[], a: { poolId: Hex; hook?: Address; account: Address }, functionName: string, args: unknown[]) {
+  const wallet = requireWallet(c);
+  const hook = a.hook ?? (await fPoolHookOf(c, a.poolId));
+  const { request } = await c.public.simulateContract({
+    address: hook,
+    abi,
+    functionName,
+    args: [a.poolId, ...args],
+    account: a.account,
+  } as never);
+  return wallet.writeContract(request as never);
+}
+
 /**
- * Propose the next authority — step one of two (contracts `2aa6b7b`, decisions 020). Nothing moves
+ * Propose the next authority — step one of two (decisions 020), on the pool's hook. Nothing moves
  * until `next` accepts; proposing again (the zero address included) cancels a pending proposal.
- * Indexed on-chain via AuthorityProposed.
+ * Indexed on-chain via the hook's AuthorityProposed.
  */
-export async function fPoolProposeAuthority(c: LogswapClient, a: { poolId: Hex; next: Address; account: Address }) {
-  return writeFPool(c, a.poolId, "proposeAuthority", [a.next], a.account);
+export async function fPoolProposeAuthority(c: LogswapClient, a: { poolId: Hex; next: Address; account: Address; hook?: Address }) {
+  return writeHook(c, fHookBaseAbi, a, "proposeAuthority", [a.next]);
 }
 
-/** Accept a pending proposal — step two; only the proposed address can. Indexed via AuthoritySet. */
-export async function fPoolAcceptAuthority(c: LogswapClient, a: { poolId: Hex; account: Address }) {
-  return writeFPool(c, a.poolId, "acceptAuthority", [], a.account);
+/**
+ * Accept a pending proposal — step two; only the proposed address can. Indexed via the hook's
+ * AuthoritySet. On the desk's hook this clears the operator (pending and accepted) and voids the
+ * seller's list (decisions 040, 044).
+ */
+export async function fPoolAcceptAuthority(c: LogswapClient, a: { poolId: Hex; account: Address; hook?: Address }) {
+  return writeHook(c, fHookBaseAbi, a, "acceptAuthority", []);
 }
 
-// ─── the sponsor's controls and the desk (contracts bd3dd87, decisions 021) ───────────────
+// ─── the desk's controls (PrivateHook; decisions 021, 044) ───────────────────────────────
 
-/** Turn the mint / swap gates on or off (authority). `burn` is never gated. */
+/** Turn the mint / swap gates on or off (the authority, on the desk's hook). `burn` is never gated. */
 export async function fPoolSetGates(
   c: LogswapClient,
-  a: { poolId: Hex; gateMint: boolean; gateSwap: boolean; account: Address },
+  a: { poolId: Hex; gateMint: boolean; gateSwap: boolean; account: Address; hook?: Address },
 ) {
-  return writeFPool(c, a.poolId, "setGates", [a.gateMint, a.gateSwap], a.account);
+  return writeHook(c, privateHookAbi, a, "setGates", [a.gateMint, a.gateSwap]);
 }
 
-/** Add to or remove from the pool's list, in one call (authority). */
+/**
+ * Add to or remove from the pool's list, in one call (the authority, on the desk's hook). The list
+ * is keyed by the authority that granted it: a handover starts the buyer with an empty one.
+ */
 export async function fPoolSetAllowed(
   c: LogswapClient,
-  a: { poolId: Hex; who: readonly Address[]; allowed: boolean; account: Address },
+  a: { poolId: Hex; who: readonly Address[]; allowed: boolean; account: Address; hook?: Address },
 ) {
-  return writeFPool(c, a.poolId, "setAllowed", [a.who, a.allowed], a.account);
+  return writeHook(c, privateHookAbi, a, "setAllowed", [a.who, a.allowed]);
 }
 
-/** Whether `who` is on the pool's list (consulted only while a gate is on). */
-export async function fPoolIsAllowed(c: LogswapClient, poolId: Hex, who: Address): Promise<boolean> {
+/** Whether `who` is on the pool's list under its current authority (consulted only while a gate is on). */
+export async function fPoolIsAllowed(c: LogswapClient, poolId: Hex, who: Address, hook?: Address): Promise<boolean> {
+  const address = hook ?? (await fPoolHookOf(c, poolId));
   return (await c.public.readContract({
-    address: c.addresses.fPoolManager!,
-    abi: fPoolManagerAbi,
-    functionName: "allowed",
+    address,
+    abi: privateHookAbi,
+    functionName: "isAllowed",
     args: [poolId, who],
   } as never)) as boolean;
 }
@@ -1165,27 +1283,27 @@ export async function fPoolSponsorName(c: LogswapClient, who: Address): Promise<
 }
 
 /** Who runs the pool (decisions 037): the appointed operator, or the authority until one is. */
-export function fPoolOperatorOf(s: Pick<FPoolState, "authority" | "operator">): Address {
+export function fPoolOperatorOf(s: Pick<FPoolRoles, "authority" | "operator">): Address {
   return s.operator === ZERO_ADDRESS ? s.authority : s.operator;
 }
 
 /**
- * Propose the operator (authority; private pools only) — the hot key that runs the pool: `harvest`,
- * `dissolve`, `setLegs`. Two-step: the proposed address takes the role with
+ * Propose the operator (the authority, on the desk's hook) — the hot key that runs the pool:
+ * `harvest`, `retire`, `regenerate`, `setLegs`. Two-step: the proposed address takes the role with
  * {@link fPoolAcceptOperator}. The zero address clears at once — the role returns to the authority.
  */
-export async function fPoolAppointOperator(c: LogswapClient, a: { poolId: Hex; operator: Address; account: Address }) {
-  return writeFPool(c, a.poolId, "appointOperator", [a.operator], a.account);
+export async function fPoolAppointOperator(c: LogswapClient, a: { poolId: Hex; operator: Address; account: Address; hook?: Address }) {
+  return writeHook(c, privateHookAbi, a, "appointOperator", [a.operator]);
 }
 
 /** The proposed operator takes the role. */
-export async function fPoolAcceptOperator(c: LogswapClient, a: { poolId: Hex; account: Address }) {
-  return writeFPool(c, a.poolId, "acceptOperator", [], a.account);
+export async function fPoolAcceptOperator(c: LogswapClient, a: { poolId: Hex; account: Address; hook?: Address }) {
+  return writeHook(c, privateHookAbi, a, "acceptOperator", []);
 }
 
 /**
  * The next generation's composition (operator; private pools only; ONLY while the pool is
- * unseeded — between a dissolve and the seed that prices it, decisions 037). `weights` has one
+ * unseeded — between a retire and the seed that prices it, decisions 037). `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
@@ -1228,7 +1346,10 @@ export interface DiscoveredFPool {
   weights: bigint[];
   phi: bigint;
   kind: FPoolKind;
-  authority: Address;
+  /** The pool's policy — the hook the key names (decisions 041, 044). */
+  hook: Address;
+  /** Who was born holding the pool (immutable). The LIVE authority is the hook's — {@link getFPoolRoles}. */
+  creator: Address;
   /** The block the pool was initialized in — its age, for annualising realized income. */
   block: bigint;
   /** Whether `seed` has run; an unseeded pool has no floor and no float, so nothing to show. */
@@ -1276,8 +1397,8 @@ export async function discoverFPools(
   }
   return logs.map((l) => {
     const a = l.args as {
-      poolId: Hex; quote: Address; authority: Address; bases: readonly Address[];
-      weights: readonly bigint[]; phi: bigint; kind: number;
+      poolId: Hex; quote: Address; creator: Address; bases: readonly Address[];
+      weights: readonly bigint[]; phi: bigint; kind: number; hook: Address;
     };
     const q0 = q0Of.get(a.poolId.toLowerCase());
     return {
@@ -1287,7 +1408,8 @@ export async function discoverFPools(
       weights: [...a.weights],
       phi: a.phi,
       kind: fPoolKindOf(a.kind),
-      authority: a.authority,
+      hook: a.hook,
+      creator: a.creator,
       block: l.blockNumber ?? 0n,
       seeded: q0 !== undefined,
       q0: q0 ?? 0n,
@@ -1296,6 +1418,87 @@ export async function discoverFPools(
   });
 }
 
+// ─── the policy page: what an authority controls (decisions 044) ────────────────────────
+//
+// One hook serves every pool of its kind, so "the pools I control" is not a hook's list: it is
+// every pool whose hook answers `authority(poolId) == me`. Discovery from the log stream (or the
+// indexer), then one `authority` read per pool on its hook — viem multicalls them.
+
+/** A pool an authority controls, with what the policy page shows of it. */
+export interface FPoolControlled {
+  pool: DiscoveredFPool;
+  roles: FPoolRoles;
+  state: FPoolState;
+  /** The hook's numbers for this pool's kind — a pad's rung and threshold, a POL's floors, the desk's list flags. */
+  policy: FPoolPolicy;
+}
+
+/** What a pool's hook says about it, by kind: the terms a buyer reads before entering. */
+export type FPoolPolicy =
+  | { kind: "pad"; harvestCut: bigint; rung: number; threshold: bigint; pot: bigint; creatorShare: bigint; protocolShare: bigint; burnPerRung: bigint }
+  | { kind: "pol"; harvestCut: bigint; keepQuote: bigint; minQuoteAtSeed: bigint }
+  | { kind: "public"; harvestCut: bigint; curated: boolean }
+  | { kind: "private"; harvestCut: bigint; gateMint: boolean; gateSwap: boolean; operator: Address };
+
+/** The hook's terms for one pool, by its kind. */
+export async function getFPoolPolicy(c: LogswapClient, s: Pick<FPoolState, "poolId" | "hook" | "kind" | "gen">, roles?: FPoolRoles): Promise<FPoolPolicy> {
+  const rd = <T>(abi: readonly unknown[], functionName: string, args: readonly unknown[] = []) =>
+    c.public.readContract({ address: s.hook, abi, functionName, args } as never) as Promise<T>;
+  const harvestCut = await rd<bigint>(fHookBaseAbi, "harvestCut");
+  switch (s.kind) {
+    case "pad": {
+      const [rung, creatorShare, protocolShare, burnPerRung, pot] = await Promise.all([
+        rd<bigint>(padHookAbi, "rung", [s.poolId]),
+        rd<bigint>(padHookAbi, "creatorShare"),
+        rd<bigint>(padHookAbi, "protocolShare"),
+        rd<bigint>(padHookAbi, "burnPerRung"),
+        fPoolDividendOf(c, s.poolId, DEAD_ADDRESS, s.gen),
+      ]);
+      const threshold = await rd<bigint>(padHookAbi, "threshold", [rung]);
+      return { kind: "pad", harvestCut, rung: Number(rung), threshold, pot, creatorShare, protocolShare, burnPerRung };
+    }
+    case "pol": {
+      const [keepQuote, minQuoteAtSeed] = await Promise.all([rd<bigint>(polHookAbi, "keepQuote"), rd<bigint>(polHookAbi, "minQuoteAtSeed")]);
+      return { kind: "pol", harvestCut, keepQuote, minQuoteAtSeed };
+    }
+    case "public": {
+      const curated = await rd<boolean>(publicHookAbi, "curated");
+      return { kind: "public", harvestCut, curated };
+    }
+    case "private": {
+      const r = roles ?? (await getFPoolRoles(c, s.poolId, s));
+      return { kind: "private", harvestCut, gateMint: r.gateMint, gateSwap: r.gateSwap, operator: fPoolOperatorOf(r) };
+    }
+  }
+}
+
+/**
+ * Every F pool `who` is the AUTHORITY of, across the four hooks — the policy page's list. Pools
+ * `who` created and handed over are not here (the buyer's page shows them); pools handed TO
+ * `who` are. `pools` may be passed (from the indexer, say) to skip the log scan.
+ */
+export async function fPoolsControlledBy(
+  c: LogswapClient,
+  who: Address,
+  opts: { pools?: DiscoveredFPool[]; fromBlock?: bigint } = {},
+): Promise<FPoolControlled[]> {
+  const pools = opts.pools ?? (await discoverFPools(c, { fromBlock: opts.fromBlock }));
+  const authorities = await Promise.all(
+    pools.map((p) =>
+      c.public.readContract({ address: p.hook, abi: fHookBaseAbi, functionName: "authority", args: [p.poolId] } as never) as Promise<Address>,
+    ),
+  );
+  const mine = pools.filter((_, i) => authorities[i]!.toLowerCase() === who.toLowerCase());
+  return Promise.all(
+    mine.map(async (pool) => {
+      const state = await getFPool(c, pool.poolId);
+      const roles = await getFPoolRoles(c, pool.poolId, state);
+      const policy = await getFPoolPolicy(c, state, roles);
+      return { pool, roles, state, policy };
+    }),
+  );
+}
+
 
 /**
  * Every holder of a pool's shares, from the ERC-6909 Transfer stream — the id is an indexed