@logswap/sdk 0.5.47 → 0.5.49

package/src/fpool.ts

@@ -14,15 +14,15 @@
  *
  * **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
+ * 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
  * 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}, …).
+ * **The roles are the policy's, not the manager's** (F version 15). The manager holds no
+ * authority, operator, gate or list: it asks the pool's policy `may(who, action)` and acts on the
+ * answer. So `getFPool` carries the policy and what it declared, {@link getFPoolRoles} reads the
+ * roles FROM the policy, and every role write — the handover, the operator, the gates, the list —
+ * is a write to the policy ({@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
@@ -31,28 +31,28 @@
  */
 
 import { encodeFunctionData, toFunctionSelector, type Address, type Hash, type Hex } from "viem";
-import { fPoolManagerAbi, logswapRouterAbi, padHookAbi, polHookAbi, privateHookAbi, publicHookAbi } from "./generated.js";
+import { fPoolManagerAbi, logswapRouterAbi, padPolicyAbi, polPolicyAbi, privatePolicyAbi, publicPolicyAbi } 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 policies in F version 15 (decisions 044): {@link fPolicyBaseAbi} is what every policy shares,
+ * {@link privatePolicyAbi} the desk's, {@link padPolicyAbi} / {@link polPolicyAbi} / {@link publicPolicyAbi}
  * the kinds'.
  */
-export { fPoolManagerAbi, padHookAbi, polHookAbi, privateHookAbi, publicHookAbi };
+export { fPoolManagerAbi, padPolicyAbi, polPolicyAbi, privatePolicyAbi, publicPolicyAbi };
 /**
- * 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.
+ * What every protocol policy shares (`FPolicyBase`): the roles and their handover, `harvestCut`,
+ * `maxHarvest`. `polPolicyAbi` 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 policies decodes the base's functions.
  */
-export const fHookBaseAbi = polHookAbi;
+export const fPolicyBaseAbi = polPolicyAbi;
 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`. */
+/** The optional questions a policy declared at birth (decisions 044), as bits of `Pool.asks`. */
 export const ASK_SWAP = 1;
 export const ASK_MINT = 2;
 
@@ -83,10 +83,10 @@ export interface FPoolState {
   /**
    * 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.
+   * {@link getFPoolRoles}; one of the deployment's four ({@link fPoolPolicyFor}) on every protocol pool.
    */
-  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. */
+  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, mutable and never identity. "" when unnamed. */
   name: string;
@@ -120,11 +120,11 @@ 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. No role in it since F version 15: those are the hook's.
+  // to be a dozen getters a single read. No role in it since F version 15: those are the policy's.
   const p = await rd<{
     quote: Address;
     phi: bigint;
-    hook: Address;
+    policy: Address;
     kind: number;
     seeded: boolean;
     gen: number;
@@ -160,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, hook, restructureBlock, seeded, gen } = p;
+  const { quote, Q, L, phi, theta0, bigSigma, policy, restructureBlock, seeded, gen } = p;
   const totalSupply = p.shares;
 
   return {
@@ -176,7 +176,7 @@ export async function getFPool(c: LogswapClient, poolId: Hex): Promise<FPoolStat
     theta,
     compositeX,
     bigSigma,
-    hook,
+    policy,
     asks: Number(p.asks),
     name: bytes32ToText(p.name),
     restructureBlock: Number(restructureBlock),
@@ -190,13 +190,13 @@ export async function getFPool(c: LogswapClient, poolId: Hex): Promise<FPoolStat
 
 /**
  * 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
+ * the pool's policy answers. `public`: the protocol's own pool — its policy requires the collector as
+ * creator; no gate, no operator. `private`, the desk: the one kind whose policy 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,
+ * income only whatever its policy 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.
+ * protocol. Every rate, role and gate is the policy's.
  */
 export type FPoolKind = "public" | "private" | "pol" | "pad";
 /** The key's enum values. */
@@ -208,35 +208,35 @@ 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 {
+/** The deployment's policy for a kind (decisions 044): what a key of that kind names. */
+export function fPoolPolicyFor(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;
+  const policy = kind === "public" ? a.publicPolicy : kind === "private" ? a.privatePolicy : kind === "pol" ? a.polPolicy : a.padPolicy;
+  if (!policy) throw new Error(`logswap: this deployment carries no ${kind} policy`);
+  return policy;
 }
 
-/** 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> {
+/** The policy a pool named in its key — one read; {@link getFPool} carries it too. */
+export async function fPoolPolicyOf(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 };
+  } as never)) as { quote: Address; policy: Address };
   if (/^0x0{40}$/i.test(p.quote)) throw new Error(`logswap: no F pool with id ${poolId}`);
-  return p.hook;
+  return p.policy;
 }
 
 /**
- * A pool's roles, as its HOOK holds them (decisions 044). `creator` is immutable identity —
+ * A pool's roles, as its POLICY 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;
+  policy: Address;
   creator: Address;
   authority: Address;
   /** The proposed next authority, until it accepts — zero when nothing is pending (decisions 020). */
@@ -245,31 +245,31 @@ export interface FPoolRoles {
   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. */
+  /** The policy's own ceiling on a harvest now — the manager's `harvestable` narrowed by the policy'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> {
+/** Read a pool's roles from its policy. `state` saves the `getPool` round trip when already in hand. */
+export async function getFPoolRoles(c: LogswapClient, poolId: Hex, state?: Pick<FPoolState, "policy" | "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 rdPolicy = <T>(abi: readonly unknown[], functionName: string) =>
+    c.public.readContract({ address: s.policy, 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"),
+    rdPolicy<Address>(fPolicyBaseAbi, "creator"),
+    rdPolicy<Address>(fPolicyBaseAbi, "authority"),
+    rdPolicy<Address>(fPolicyBaseAbi, "pendingAuthority"),
+    rdPolicy<bigint>(fPolicyBaseAbi, "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"),
+        rdPolicy<Address>(privatePolicyAbi, "operator"),
+        rdPolicy<Address>(privatePolicyAbi, "pendingOperator"),
+        rdPolicy<boolean>(privatePolicyAbi, "gateMint"),
+        rdPolicy<boolean>(privatePolicyAbi, "gateSwap"),
       ])
     : [ZERO_ADDRESS, ZERO_ADDRESS, false, false];
-  return { hook: s.hook, creator, authority, pendingAuthority, operator, pendingOperator, gateMint, gateSwap, maxHarvest };
+  return { policy: s.policy, 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. */
@@ -287,7 +287,7 @@ export interface FPoolDescription {
    * 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}. */
+  /** 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). */
   pot: bigint;
@@ -870,11 +870,11 @@ export interface FPoolCreateArgs {
   kind: FPoolKind;
   /**
    * 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
+   * for the kind. Defaults to the deployment's policy for `kind` ({@link fPoolPolicyFor}) — 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). */
+  policy?: Address;
+  /** Who is born holding the pool: immutable identity, the pool's first authority (the policy records it). */
   creator: Address;
   /**
    * The differentiator, and nothing else. Identity is the key's hash, so one sponsor cannot run
@@ -909,7 +909,7 @@ 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. */
+/** The key as the manager hashes it: legs sorted, the kind's policy filled in when none is named. */
 export function fPoolKeyOf(c: LogswapClient, a: Omit<FPoolCreateArgs, "account">) {
   const { bases, companions } = sortFPoolLegs(a.bases, a.weights);
   return {
@@ -918,7 +918,7 @@ export function fPoolKeyOf(c: LogswapClient, a: Omit<FPoolCreateArgs, "account">
     weights: companions[0]!,
     phi: a.phi,
     kind: F_KIND[a.kind],
-    hook: a.hook ?? fPoolHookFor(c, a.kind),
+    policy: a.policy ?? fPoolPolicyFor(c, a.kind),
     creator: a.creator,
     salt: a.salt ?? ZERO_SALT,
   };
@@ -984,7 +984,7 @@ export async function fPoolSeed(
  * 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.
+ * which opens generation `gen + 1` under the same id, policy, roles, gates and lists.
  */
 export async function fPoolRetireRaw(c: LogswapClient, a: { poolId: Hex; account: Address }) {
   return writeFPool(c, a.poolId, "retire", [], a.account);
@@ -1010,25 +1010,25 @@ export async function fPoolRetire(c: LogswapClient, a: { poolId: Hex; account: A
  * `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.
+ * 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.
  */
 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)");
   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)");
+  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)");
   return [s.Q];
 }
 
 /**
- * Release the dead shares' pot under the hook's terms (decisions 041, 044) — a pad's graduation.
+ * Release the dead shares' pot under the policy'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
+ * 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
- * float the pool owns, a slice of every reserve burned. The hook refuses under its rung's
- * threshold (`PadHook.NotGraduated`). Whoever runs the pool.
+ * float the pool owns, a slice of every reserve burned. The policy refuses under its rung's
+ * threshold (`PadPolicy.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);
@@ -1041,7 +1041,7 @@ export async function fPoolRegenerate(c: LogswapClient, a: { poolId: Hex; to?: A
  * 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. The hook, its roles, gates, allowlist and the name carry over; anything else goes
+ * authority's. The policy, 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`.
@@ -1120,8 +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);
-  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 };
+  if (!a.policy) throw new Error("logswap: fPoolLaunchCalls needs the key's policy — fPoolLaunch fills it from the deployment");
+  const key = { quote: a.quote, bases, weights: companions[0]!, phi: a.phi, kind: F_KIND[a.kind], policy: a.policy, 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[] = [];
@@ -1135,22 +1135,22 @@ 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)]));
-  // the desk's gates and list are the HOOK's (decisions 044), not the manager's: they cannot ride
+  // the desk's gates and list are the POLICY'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
+ * The desk's opening posture, on its policy (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).
+ * to `PrivatePolicy`; 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");
+export async function fPoolDeskOpening(c: LogswapClient, a: { poolId: Hex; account: Address; policy?: Address }): Promise<Hash[]> {
+  const policy = a.policy ?? fPoolPolicyFor(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 }),
+    await fPoolSetGates(c, { poolId: a.poolId, gateMint: true, gateSwap: false, account: a.account, policy }),
+    await fPoolSetAllowed(c, { poolId: a.poolId, who: [a.account], allowed: true, account: a.account, policy }),
   ];
 }
 
@@ -1176,22 +1176,22 @@ export async function fPoolLaunch(
   a: FPoolLaunchArgs & ({ r0: bigint[] } | { x0: bigint[] }),
 ): Promise<{ hash: Hash; poolId: Hex }> {
   const poolId = await fPoolIdOf(c, a);
-  const calls = fPoolLaunchCalls(poolId, { ...a, hook: a.hook ?? fPoolHookFor(c, a.kind) });
+  const calls = fPoolLaunchCalls(poolId, { ...a, policy: a.policy ?? fPoolPolicyFor(c, a.kind) });
   const hash = await writeFPool0(c, "multicall", [calls], a.account);
   return { hash, poolId };
 }
 
-// ─── the roles, on the hook (decisions 044) ─────────────────────────────────────────────
+// ─── the roles, on the policy (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.
+// 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.
 
-/** 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[]) {
+/** A write keyed by poolId, on the pool's policy. */
+async function writePolicy(c: LogswapClient, abi: readonly unknown[], a: { poolId: Hex; policy?: Address; account: Address }, functionName: string, args: unknown[]) {
   const wallet = requireWallet(c);
-  const hook = a.hook ?? (await fPoolHookOf(c, a.poolId));
+  const policy = a.policy ?? (await fPoolPolicyOf(c, a.poolId));
   const { request } = await c.public.simulateContract({
-    address: hook,
+    address: policy,
     abi,
     functionName,
     args: [a.poolId, ...args],
@@ -1201,50 +1201,50 @@ async function writeHook(c: LogswapClient, abi: readonly unknown[], a: { poolId:
 }
 
 /**
- * Propose the next authority — step one of two (decisions 020), on the pool's hook. Nothing moves
+ * Propose the next authority — step one of two (decisions 020), 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 hook's AuthorityProposed.
+ * Indexed on-chain via the policy's AuthorityProposed.
  */
-export async function fPoolProposeAuthority(c: LogswapClient, a: { poolId: Hex; next: Address; account: Address; hook?: Address }) {
-  return writeHook(c, fHookBaseAbi, a, "proposeAuthority", [a.next]);
+export async function fPoolProposeAuthority(c: LogswapClient, a: { poolId: Hex; next: Address; account: Address; policy?: Address }) {
+  return writePolicy(c, fPolicyBaseAbi, a, "proposeAuthority", [a.next]);
 }
 
 /**
- * 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
+ * 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).
  */
-export async function fPoolAcceptAuthority(c: LogswapClient, a: { poolId: Hex; account: Address; hook?: Address }) {
-  return writeHook(c, fHookBaseAbi, a, "acceptAuthority", []);
+export async function fPoolAcceptAuthority(c: LogswapClient, a: { poolId: Hex; account: Address; policy?: Address }) {
+  return writePolicy(c, fPolicyBaseAbi, a, "acceptAuthority", []);
 }
 
-// ─── the desk's controls (PrivateHook; decisions 021, 044) ───────────────────────────────
+// ─── the desk's controls (PrivatePolicy; decisions 021, 044) ───────────────────────────────
 
-/** Turn the mint / swap gates on or off (the authority, on the desk's hook). `burn` is never gated. */
+/** Turn the mint / swap gates on or off (the authority, on the desk's policy). `burn` is never gated. */
 export async function fPoolSetGates(
   c: LogswapClient,
-  a: { poolId: Hex; gateMint: boolean; gateSwap: boolean; account: Address; hook?: Address },
+  a: { poolId: Hex; gateMint: boolean; gateSwap: boolean; account: Address; policy?: Address },
 ) {
-  return writeHook(c, privateHookAbi, a, "setGates", [a.gateMint, a.gateSwap]);
+  return writePolicy(c, privatePolicyAbi, a, "setGates", [a.gateMint, a.gateSwap]);
 }
 
 /**
- * Add to or remove from the pool's list, in one call (the authority, on the desk's hook). The list
+ * Add to or remove from the pool's list, 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.
  */
 export async function fPoolSetAllowed(
   c: LogswapClient,
-  a: { poolId: Hex; who: readonly Address[]; allowed: boolean; account: Address; hook?: Address },
+  a: { poolId: Hex; who: readonly Address[]; allowed: boolean; account: Address; policy?: Address },
 ) {
-  return writeHook(c, privateHookAbi, a, "setAllowed", [a.who, a.allowed]);
+  return writePolicy(c, privatePolicyAbi, a, "setAllowed", [a.who, a.allowed]);
 }
 
 /** 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));
+export async function fPoolIsAllowed(c: LogswapClient, poolId: Hex, who: Address, policy?: Address): Promise<boolean> {
+  const address = policy ?? (await fPoolPolicyOf(c, poolId));
   return (await c.public.readContract({
     address,
-    abi: privateHookAbi,
+    abi: privatePolicyAbi,
     functionName: "isAllowed",
     args: [poolId, who],
   } as never)) as boolean;
@@ -1288,17 +1288,17 @@ export function fPoolOperatorOf(s: Pick<FPoolRoles, "authority" | "operator">):
 }
 
 /**
- * Propose the operator (the authority, on the desk's hook) — the hot key that runs the pool:
+ * Propose the operator (the authority, on the desk's policy) — 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; hook?: Address }) {
-  return writeHook(c, privateHookAbi, a, "appointOperator", [a.operator]);
+export async function fPoolAppointOperator(c: LogswapClient, a: { poolId: Hex; operator: Address; account: Address; policy?: Address }) {
+  return writePolicy(c, privatePolicyAbi, a, "appointOperator", [a.operator]);
 }
 
 /** The proposed operator takes the role. */
-export async function fPoolAcceptOperator(c: LogswapClient, a: { poolId: Hex; account: Address; hook?: Address }) {
-  return writeHook(c, privateHookAbi, a, "acceptOperator", []);
+export async function fPoolAcceptOperator(c: LogswapClient, a: { poolId: Hex; account: Address; policy?: Address }) {
+  return writePolicy(c, privatePolicyAbi, a, "acceptOperator", []);
 }
 
 /**
@@ -1346,9 +1346,9 @@ export interface DiscoveredFPool {
   weights: bigint[];
   phi: bigint;
   kind: FPoolKind;
-  /** 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}. */
+  /** The pool's policy — the contract the key names (decisions 041, 044, 045). */
+  policy: Address;
+  /** Who was born holding the pool (immutable). The LIVE authority is the policy's — {@link getFPoolRoles}. */
   creator: Address;
   /** The block the pool was initialized in — its age, for annualising realized income. */
   block: bigint;
@@ -1398,7 +1398,7 @@ export async function discoverFPools(
   return logs.map((l) => {
     const a = l.args as {
       poolId: Hex; quote: Address; creator: Address; bases: readonly Address[];
-      weights: readonly bigint[]; phi: bigint; kind: number; hook: Address;
+      weights: readonly bigint[]; phi: bigint; kind: number; policy: Address;
     };
     const q0 = q0Of.get(a.poolId.toLowerCase());
     return {
@@ -1408,7 +1408,7 @@ export async function discoverFPools(
       weights: [...a.weights],
       phi: a.phi,
       kind: fPoolKindOf(a.kind),
-      hook: a.hook,
+      policy: a.policy,
       creator: a.creator,
       block: l.blockNumber ?? 0n,
       seeded: q0 !== undefined,
@@ -1420,49 +1420,49 @@ 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.
+// 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
+// indexer), then one `authority` read per pool on its policy — 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;
+  /** The policy's numbers for this pool's kind — a pad's rung and threshold, a POL's floors, the desk's list flags. */
+  rules: FPoolRules;
 }
 
-/** What a pool's hook says about it, by kind: the terms a buyer reads before entering. */
-export type FPoolPolicy =
+/** What a pool's policy says about it, by kind: the terms a buyer reads before entering. */
+export type FPoolRules =
   | { 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> {
+/** The policy's terms for one pool, by its kind. */
+export async function getFPoolRules(c: LogswapClient, s: Pick<FPoolState, "poolId" | "policy" | "kind" | "gen">, roles?: FPoolRoles): Promise<FPoolRules> {
   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");
+    c.public.readContract({ address: s.policy, abi, functionName, args } as never) as Promise<T>;
+  const harvestCut = await rd<bigint>(fPolicyBaseAbi, "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"),
+        rd<bigint>(padPolicyAbi, "rung", [s.poolId]),
+        rd<bigint>(padPolicyAbi, "creatorShare"),
+        rd<bigint>(padPolicyAbi, "protocolShare"),
+        rd<bigint>(padPolicyAbi, "burnPerRung"),
         fPoolDividendOf(c, s.poolId, DEAD_ADDRESS, s.gen),
       ]);
-      const threshold = await rd<bigint>(padHookAbi, "threshold", [rung]);
+      const threshold = await rd<bigint>(padPolicyAbi, "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")]);
+      const [keepQuote, minQuoteAtSeed] = await Promise.all([rd<bigint>(polPolicyAbi, "keepQuote"), rd<bigint>(polPolicyAbi, "minQuoteAtSeed")]);
       return { kind: "pol", harvestCut, keepQuote, minQuoteAtSeed };
     }
     case "public": {
-      const curated = await rd<boolean>(publicHookAbi, "curated");
+      const curated = await rd<boolean>(publicPolicyAbi, "curated");
       return { kind: "public", harvestCut, curated };
     }
     case "private": {
@@ -1473,7 +1473,7 @@ export async function getFPoolPolicy(c: LogswapClient, s: Pick<FPoolState, "pool
 }
 
 /**
- * Every F pool `who` is the AUTHORITY of, across the four hooks — the policy page's list. Pools
+ * Every F pool `who` is the AUTHORITY of, across the four policies — 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.
  */
@@ -1485,7 +1485,7 @@ export async function fPoolsControlledBy(
   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>,
+      c.public.readContract({ address: p.policy, abi: fPolicyBaseAbi, functionName: "authority", args: [p.poolId] } as never) as Promise<Address>,
     ),
   );
   const mine = pools.filter((_, i) => authorities[i]!.toLowerCase() === who.toLowerCase());
@@ -1493,8 +1493,8 @@ export async function fPoolsControlledBy(
     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 };
+      const rules = await getFPoolRules(c, state, roles);
+      return { pool, roles, state, rules };
     }),
   );
 }