@logswap/sdk 0.5.44 → 0.5.46

package/dist/fpool.js

@@ -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
@@ -23,17 +30,26 @@
  * `addresses.router`.
  */
 import { encodeFunctionData, toFunctionSelector } 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): `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 };
 /**
- * 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.
+ * 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;
 const WAD = 10n ** 18n;
 const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+/** 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;
 /** Read a basket pool whole. Batched — viem multicalls these when the transport allows. */
 export async function getFPool(c, poolId) {
     // viem types `functionName` as a literal union; this reader is deliberately generic, so the
@@ -45,7 +61,7 @@ export async function getFPool(c, poolId) {
         args,
     });
     // `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("getPool", [poolId]);
     // A pool that was never created reads as an all-zero struct rather than reverting, so the
     // absence has to be named here or every caller mistakes "no such pool" for "a pool holding
@@ -67,7 +83,7 @@ export async function getFPool(c, poolId) {
     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 {
         poolId,
@@ -82,13 +98,9 @@ export async function getFPool(c, poolId) {
         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,
@@ -106,24 +118,65 @@ export function fPoolKindOf(n) {
         throw new Error(`logswap: unknown pool kind ${n}`);
     return k;
 }
+/** The deployment's hook for a kind (decisions 044): what a key of that kind names. */
+export function fPoolHookFor(c, kind) {
+    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, poolId) {
+    const p = (await c.public.readContract({
+        address: c.addresses.fPoolManager,
+        abi: fPoolManagerAbi,
+        functionName: "getPool",
+        args: [poolId],
+    }));
+    if (/^0x0{40}$/i.test(p.quote))
+        throw new Error(`logswap: no F pool with id ${poolId}`);
+    return p.hook;
+}
+/** Read a pool's roles from its hook. `state` saves the `getPool` round trip when already in hand. */
+export async function getFPoolRoles(c, poolId, state) {
+    const s = state ?? (await getFPool(c, poolId));
+    const rdHook = (abi, functionName) => c.public.readContract({ address: s.hook, abi, functionName, args: [poolId] });
+    const [creator, authority, pendingAuthority, maxHarvest] = await Promise.all([
+        rdHook(fHookBaseAbi, "creator"),
+        rdHook(fHookBaseAbi, "authority"),
+        rdHook(fHookBaseAbi, "pendingAuthority"),
+        rdHook(fHookBaseAbi, "maxHarvest"),
+    ]);
+    const desk = s.kind === "private";
+    const [operator, pendingOperator, gateMint, gateSwap] = desk
+        ? await Promise.all([
+            rdHook(privateHookAbi, "operator"),
+            rdHook(privateHookAbi, "pendingOperator"),
+            rdHook(privateHookAbi, "gateMint"),
+            rdHook(privateHookAbi, "gateSwap"),
+        ])
+        : [ZERO_ADDRESS, ZERO_ADDRESS, false, false];
+    return { hook: s.hook, creator, authority, pendingAuthority, operator, pendingOperator, gateMint, gateSwap, maxHarvest };
+}
 export async function describeFPool(c, s) {
-    const rd = (functionName) => c.public.readContract({
+    const rd = (functionName, args = [s.poolId]) => c.public.readContract({
         address: c.addresses.fPoolManager,
         abi: fPoolManagerAbi,
         functionName,
-        args: [s.poolId],
+        args,
     });
-    // 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("feePerL"), rd("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("unharvested"), rd("harvestable"), rd("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,
     };
 }
 /** `p_j = e^{x_j}`, lossy the way any float conversion is. Compare in log space when it matters. */
@@ -553,13 +606,26 @@ export function sortFPoolLegs(bases, ...companions) {
     const idx = bases.map((_, i) => i).sort((a, b) => (bases[a].toLowerCase() < bases[b].toLowerCase() ? -1 : 1));
     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, a) {
+    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, a) {
     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,
@@ -572,8 +638,7 @@ export async function fPoolInitialize(c, a) {
 }
 /** The pool id is the key's hash — pure, so it can be read before or after creation. */
 export async function fPoolIdOf(c, a) {
-    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,
@@ -604,81 +669,71 @@ export async function fPoolSeed(c, a) {
     return writeFPool(c, a.poolId, "seed", [a.L0, r0, a.Q0], a.account);
 }
 /**
- * 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, a) {
-    return writeFPool(c, a.poolId, "dissolve", [], a.account);
+export async function fPoolRetireRaw(c, a) {
+    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, a) {
     const harvests = await fPoolEmptyingHarvests(c, a.poolId);
     if (harvests.length === 0)
-        return fPoolDissolve(c, a);
+        return fPoolRetireRaw(c, a);
     const enc = (functionName, args) => encodeFunctionData({ abi: fPoolManagerAbi, functionName, args });
-    const calls = [...harvests.map((amount) => enc("harvest", [a.poolId, amount, a.account])), enc("dissolve", [a.poolId])];
+    const calls = [...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, poolId) {
-    const rd = (functionName, args = []) => c.public.readContract({ address: c.addresses.fPoolManager, abi: fPoolManagerAbi, functionName, args });
-    const [p, feePerL, fee, exempt, collector] = await Promise.all([
-        rd("getPool", [poolId]),
-        rd("feePerL", [poolId]),
-        rd("HARVEST_PROTOCOL_CUT"),
-        rd("harvestCutExempt", [poolId]),
-        rd("feeCollector"),
-    ]);
-    if (p.Q === 0n)
+    const s = await getFPool(c, poolId);
+    if (s.Q === 0n)
         return [];
-    if (p.kind === F_KIND.pad)
+    if (s.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 = [];
-    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 { 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, a) {
+    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, a) {
     const [gen, harvests] = await Promise.all([fPoolGen(c, a.poolId), fPoolEmptyingHarvests(c, a.poolId)]);
@@ -686,7 +741,7 @@ export async function fPoolRelaunch(c, a) {
     const enc = (functionName, args) => encodeFunctionData({ abi: fPoolManagerAbi, functionName, args });
     const calls = [
         ...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]),
@@ -712,7 +767,9 @@ export function fPoolLaunchCalls(poolId, a) {
     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, args) => encodeFunctionData({ abi: fPoolManagerAbi, functionName, args });
     const calls = [];
     if (!a.initialized)
@@ -728,15 +785,23 @@ export function fPoolLaunchCalls(poolId, a) {
     }
     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, a) {
+    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.
@@ -756,36 +821,62 @@ export function fPoolLaunchCalls(poolId, a) {
  */
 export async function fPoolLaunch(c, a) {
     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, abi, a, functionName, args) {
+    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,
+    });
+    return wallet.writeContract(request);
+}
 /**
- * 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, a) {
-    return writeFPool(c, a.poolId, "proposeAuthority", [a.next], a.account);
+    return writeHook(c, fHookBaseAbi, a, "proposeAuthority", [a.next]);
 }
-/** Accept a pending proposal — step two; only the proposed address can. Indexed via AuthoritySet. */
+/**
+ * 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, a) {
-    return writeFPool(c, a.poolId, "acceptAuthority", [], a.account);
+    return writeHook(c, fHookBaseAbi, a, "acceptAuthority", []);
 }
-// ─── the sponsor's controls and the desk (contracts bd3dd87, decisions 021) ───────────────
-/** Turn the mint / swap gates on or off (authority). `burn` is never gated. */
+// ─── the desk's controls (PrivateHook; decisions 021, 044) ───────────────────────────────
+/** Turn the mint / swap gates on or off (the authority, on the desk's hook). `burn` is never gated. */
 export async function fPoolSetGates(c, a) {
-    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, a) {
-    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, poolId, who) {
+/** Whether `who` is on the pool's list under its current authority (consulted only while a gate is on). */
+export async function fPoolIsAllowed(c, poolId, who, hook) {
+    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],
     }));
 }
@@ -823,20 +914,20 @@ export function fPoolOperatorOf(s) {
     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, a) {
-    return writeFPool(c, a.poolId, "appointOperator", [a.operator], a.account);
+    return writeHook(c, privateHookAbi, a, "appointOperator", [a.operator]);
 }
 /** The proposed operator takes the role. */
 export async function fPoolAcceptOperator(c, a) {
-    return writeFPool(c, a.poolId, "acceptOperator", [], a.account);
+    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
@@ -898,7 +989,8 @@ export async function discoverFPools(c, opts = {}) {
             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,
@@ -906,6 +998,52 @@ export async function discoverFPools(c, opts = {}) {
         };
     });
 }
+/** The hook's terms for one pool, by its kind. */
+export async function getFPoolPolicy(c, s, roles) {
+    const rd = (abi, functionName, args = []) => c.public.readContract({ address: s.hook, abi, functionName, args });
+    const harvestCut = await rd(fHookBaseAbi, "harvestCut");
+    switch (s.kind) {
+        case "pad": {
+            const [rung, creatorShare, protocolShare, burnPerRung, pot] = await Promise.all([
+                rd(padHookAbi, "rung", [s.poolId]),
+                rd(padHookAbi, "creatorShare"),
+                rd(padHookAbi, "protocolShare"),
+                rd(padHookAbi, "burnPerRung"),
+                fPoolDividendOf(c, s.poolId, DEAD_ADDRESS, s.gen),
+            ]);
+            const threshold = await rd(padHookAbi, "threshold", [rung]);
+            return { kind: "pad", harvestCut, rung: Number(rung), threshold, pot, creatorShare, protocolShare, burnPerRung };
+        }
+        case "pol": {
+            const [keepQuote, minQuoteAtSeed] = await Promise.all([rd(polHookAbi, "keepQuote"), rd(polHookAbi, "minQuoteAtSeed")]);
+            return { kind: "pol", harvestCut, keepQuote, minQuoteAtSeed };
+        }
+        case "public": {
+            const curated = await rd(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, who, opts = {}) {
+    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] })));
+    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
  * topic, so one filtered log query aggregates the whole ledger. The 0xdead entry is the