@logswap/sdk 0.5.71 → 0.5.72

package/src/fpool.ts

@@ -31,7 +31,7 @@
  */
 
 import { decodeAbiParameters, encodeAbiParameters, encodeFunctionData, erc20Abi, keccak256, toFunctionSelector, type Address, type Hash, type Hex } from "viem";
-import { fPoolManagerAbi, logswapRouterAbi, padPolicyAbi, polPolicyAbi, policyRegistryAbi, privatePolicyAbi, publicPolicyAbi } from "./generated.js";
+import { fPoolManagerAbi, logswapLensAbi, logswapRouterAbi, padPolicyAbi, polPolicyAbi, policyRegistryAbi, privatePolicyAbi, publicPolicyAbi } from "./generated.js";
 
 /**
  * One contract, one ABI (F version 12): `harvest`, `claim`, `retire`, `regenerate`,
@@ -72,14 +72,21 @@ export interface FPoolState {
   Q: bigint;
   /** Total exposure. Grows on mint, shrinks on burn; never moves on a swap. */
   L: bigint;
-  /** Fixed fee, WAD. At or above `FEE_MIN` — a zero-fee basket is not constructible. */
-  phi: bigint;
-  /** The strike: θ at seeding, and the fees-only harvest bound. */
-  theta0: bigint;
-  /** θ = X − Q/L, the shared floor. Derived from the holdings, never stored. */
-  theta: bigint;
+  /** The swap fee, WAD (`phi` before F version 25, decisions 059). At or above `FEE_MIN` — a zero-fee basket is not constructible. */
+  swapFee: bigint;
+  /** θ₀, the reference log floor: where the floor stood at the seed (re-based by a capital harvest and at each step); income is counted from it. `theta0` before F version 25. */
+  refLogFloor: bigint;
+  /** θ = X − Q/L, the log of the pool's current floor price: where the bid runs out. Derived, never stored. `theta` before F version 25. */
+  logFloor: bigint;
   /** X = Σ w_j x_j, the composite index. */
   compositeX: bigint;
+  /** This generation's income still in the pool, quote: L·(θ₀ − θ). */
+  unharvested: bigint;
+  /**
+   * The common cap (decisions 061): d = ln(cap price / floor price) in 1e-6 log units, from the key;
+   * 0 is uncapped. Leverage at the floor is 1/(1 − e^{−d}): {@link fPoolLeverageOfCap}.
+   */
+  cap: number;
   /** Σ = ∫ Σ_j w_j (dx_j)², accrued even though the fee is fixed — the kernel stays calculable. */
   bigSigma: bigint;
   /**
@@ -110,87 +117,69 @@ export interface FPoolState {
   totalSupply: bigint;
   /** What the pool holds of each base — the STATE; the mark `x` is derived from it. */
   reserves: bigint[];
+  /** The reserve every price reads: `reserves[j] + L_j·κ_j` on a capped pool (061), `reserves[j]` otherwise. */
+  virtualReserves: bigint[];
+  /** κ_j = e^{−μ_j}, WAD: each leg's phantom reserve per unit of its liquidity. 0 uncapped. */
+  kappa: bigint[];
 }
 
-/** Read a basket pool whole. Batched — viem multicalls these when the transport allows. */
-export async function getFPool(c: LogswapClient, poolId: Hex): Promise<FPoolState> {
-  // viem types `functionName` as a literal union; this reader is deliberately generic, so the
-  // cast lives here once rather than at each call site below.
-  const rd = <T>(functionName: string, args: readonly unknown[]) =>
-    c.public.readContract({
-      address: c.addresses.fPoolManager!,
-      abi: fPoolManagerAbi,
-      functionName,
-      args,
-    } 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, no kind and no name
-  // since 18: those are the policy's.
-  const p = await rd<{
-    quote: Address;
-    phi: bigint;
-    policy: Address;
-    seeded: boolean;
-    gen: number;
-    n: number;
-    restructureBlock: number;
-    asks: number;
-    Q: bigint;
-    bigSigma: bigint;
-    L: bigint;
-    shares: bigint;
-    theta0: bigint;
-  }>("getPool", [poolId]);
+/**
+ * The lens's raw F pool struct — what the manager's `getPool` returned. Since F version 25 the
+ * manager's typed views are behind `extsload` (decisions 062) and the lens reads them; one call.
+ */
+async function rawFPool(c: LogswapClient, poolId: Hex) {
+  const [p] = await c.public.readContract({
+    address: c.addresses.lens,
+    abi: logswapLensAbi,
+    functionName: "getFPools",
+    args: [[poolId]],
+  });
+  if (!p || /^0x0{40}$/i.test(p.quote)) throw new Error(`logswap: no F pool with id ${poolId}`);
+  return p;
+}
 
+/** Read a basket pool whole: one lens call (`fPool`, F version 25) plus the policy's kind and name. */
+export async function getFPool(c: LogswapClient, poolId: Hex): Promise<FPoolState> {
+  const v = await c.public.readContract({
+    address: c.addresses.lens,
+    abi: logswapLensAbi,
+    functionName: "fPool",
+    args: [poolId],
+  });
+  const p = v.pool;
   // 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
   // nothing". `quote` is the manager's own existence test (`_live`), and it is what the create
   // flow's resumability turns on: an initialized-but-unseeded pool MUST still read, so this
   // cannot be a check on `seeded`.
   if (/^0x0{40}$/i.test(p.quote)) throw new Error(`logswap: no F pool with id ${poolId}`);
-
-  const n = Number(p.n);
-  const idx = Array.from({ length: n }, (_, i) => BigInt(i));
-  const [theta, compositeX, legs, kind, name] = await Promise.all([
-    // before the seed there is no L and no floor: θ is X by convention (older deployments revert
-    // with DivWadFailed, so do not ask them)
-    p.L > 0n ? rd<bigint>("theta", [poolId]) : rd<bigint>("compositeX", [poolId]),
-    rd<bigint>("compositeX", [poolId]),
-    Promise.all(idx.map((i) => rd<readonly [Address, bigint, bigint, bigint]>("legOf", [poolId, i]))),
-    fPoolKindOfPolicy(c, p.policy),
-    fPoolNameOf(c, poolId, p.policy),
-  ]);
-
-  const bases = legs.map((l) => l[0]);
-  const weights = legs.map((l) => l[1]);
-  const x = legs.map((l) => l[2]); // derived by the manager: x_j = ln(w_j·L / R_j) 
-  const reserves = legs.map((l) => l[3]); // the state
-  const { quote, Q, L, phi, theta0, bigSigma, policy, restructureBlock, seeded, gen } = p;
-  const totalSupply = p.shares;
-
+  const [kind, name] = await Promise.all([fPoolKindOfPolicy(c, p.policy), fPoolNameOf(c, poolId, p.policy)]);
   return {
     poolId,
-    quote,
-    bases,
-    weights,
-    x,
-    Q,
-    L,
-    phi,
-    theta0,
-    theta,
-    compositeX,
-    bigSigma,
-    policy,
+    quote: p.quote,
+    bases: v.legs.map((l) => l.base),
+    weights: v.legs.map((l) => l.weight),
+    x: v.legs.map((l) => l.x), // derived by the manager: x_j = ln(w_j·L / R̃_j)
+    Q: p.Q,
+    L: p.L,
+    swapFee: p.swapFee,
+    refLogFloor: p.refLogFloor,
+    logFloor: v.logFloor,
+    compositeX: v.compositeX,
+    unharvested: v.unharvested,
+    cap: Number(p.cap),
+    bigSigma: p.bigSigma,
+    policy: p.policy,
     asks: Number(p.asks),
     name,
-    restructureBlock: Number(restructureBlock),
+    restructureBlock: Number(p.restructureBlock),
     kind,
-    seeded,
-    gen: Number(gen),
-    totalSupply,
-    reserves,
+    seeded: p.seeded,
+    gen: Number(p.gen),
+    totalSupply: p.shares,
+    reserves: v.legs.map((l) => l.reserve), // the state
+    virtualReserves: v.legs.map((l) => l.virtualReserve),
+    kappa: v.legs.map((l) => l.kappa),
   };
 }
 
@@ -248,14 +237,7 @@ export function fPoolPolicyFor(c: LogswapClient, kind: FPoolKind): 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; policy: Address };
-  if (/^0x0{40}$/i.test(p.quote)) throw new Error(`logswap: no F pool with id ${poolId}`);
-  return p.policy;
+  return (await rawFPool(c, poolId)).policy;
 }
 
 /**
@@ -329,19 +311,11 @@ export interface FPoolDescription {
 }
 
 export async function describeFPool(c: LogswapClient, s: FPoolState): Promise<FPoolDescription> {
-  const rd = <T>(functionName: string, args: readonly unknown[] = [s.poolId]) =>
-    c.public.readContract({
-      address: c.addresses.fPoolManager!,
-      abi: fPoolManagerAbi,
-      functionName,
-      args,
-    } as never) as Promise<T>;
   // an unseeded pool has no L: nothing earned, nothing to harvest, no pot. The bid is the
   // manager's ceiling (`harvestable()` until F version 21, which cut the getter): Q once seeded.
   const harvestable = s.L > 0n ? s.Q : 0n;
-  const [unharvested, pot] = s.L > 0n
-    ? await Promise.all([rd<bigint>("unharvested"), rd<bigint>("dividendOf", [s.poolId, BigInt(s.gen), DEAD_ADDRESS])])
-    : [0n, 0n];
+  const unharvested = s.L > 0n ? s.unharvested : 0n;
+  const pot = s.L > 0n ? await fPoolDividendOf(c, s.poolId, DEAD_ADDRESS, s.gen) : 0n;
   return {
     shape: s.kind === "pad" ? "launch": "basket", // the kind, not n = 1 
     legs: s.bases.length,
@@ -357,10 +331,22 @@ export function fPoolPriceOf(x: bigint, scale = 1): number {
   return Math.exp(Number(x) / 1e18) * scale;
 }
 
-/** Value per share at the pool's own marks. `V = L + Q`, so this is just that, pro-rated. */
+/**
+ * Value per share at the pool's own marks, WAD. Uncapped, `V = L + Q`. Capped (decisions 061), leg
+ * j's base is worth `L_j·R_j/R̃_j`, less than `L_j` by the phantom the cap removed — the lens's
+ * `shareValue`, without the call.
+ */
 export function fPoolShareValue(s: FPoolState): bigint {
   if (s.totalSupply === 0n) return 0n;
-  return ((s.L + s.Q) * WAD) / s.totalSupply;
+  let v = s.L + s.Q;
+  if (s.cap !== 0) {
+    v = s.Q;
+    for (let j = 0; j < s.reserves.length; j++) {
+      const rv = s.virtualReserves[j]!;
+      if (rv !== 0n) v += (((s.weights[j]! * s.L) / WAD) * s.reserves[j]!) / rv;
+    }
+  }
+  return (v * WAD) / s.totalSupply;
 }
 
 // ─── swaps ────────────────────────────────────────────────────────────────────
@@ -624,15 +610,84 @@ export async function fPoolClaim(c: LogswapClient, a: { poolId: Hex; gen?: bigin
   return writeFPool(c, a.poolId, "claim", [BigInt(gen), a.to ?? a.account], a.account);
 }
 
-/** A holder's dividend as of now on generation `gen` (the live one by default) — banked plus pending on the current balance. */
+/**
+ * A holder's claimable dividend as of now on generation `gen` (the live one by default) — banked
+ * plus pending on the current balance; under a lien, the free fraction's only: the locked
+ * fraction's is the lien's ({@link fPoolLienOf}, decisions 063).
+ */
 export async function fPoolDividendOf(c: LogswapClient, poolId: Hex, holder: Address, gen?: bigint | number): Promise<bigint> {
   const g = gen ?? (await fPoolGen(c, poolId));
   return c.public.readContract({
-    address: c.addresses.fPoolManager!,
-    abi: fPoolManagerAbi,
-    functionName: "dividendOf",
+    address: c.addresses.lens,
+    abi: logswapLensAbi,
+    functionName: "fDividendOf",
     args: [poolId, BigInt(g), holder],
-  } as never) as Promise<bigint>;
+  });
+}
+
+// ─── the lien (decisions 063) ─────────────────────────────────────────────────
+// A lending contract — the LOCKER — locks part of an owner's shares in place: no transfer, burn or
+// redeem past the free balance. The dividend the locked amount earns is HELD BY THE LIEN, claimable
+// by nobody while it stands; lifted, it goes with the lifted part — to the owner on a release (a
+// repaid loan gets it back), to the seizer on a seizure. A borrower frozen out by `regenerate` keeps
+// its lien on the old generation's id.
+
+/** A lien on one share id: the locker, the amount locked, and the dividend the lien holds (banked). */
+export interface FPoolLien {
+  locker: Address;
+  amount: bigint;
+  owed: bigint;
+}
+
+/**
+ * The lien on `owner`'s shares of `poolId`'s generation `gen` (the live one by default). `owed` counts
+ * what has been banked into it; the locked fraction of the owner's pending since its last bank is
+ * not yet in it — {@link fPoolBankLien} banks it.
+ */
+export async function fPoolLienOf(c: LogswapClient, poolId: Hex, owner: Address, gen?: bigint | number): Promise<FPoolLien> {
+  const g = gen ?? (await fPoolGen(c, poolId));
+  const [locker, amount, owed] = await c.public.readContract({
+    address: c.addresses.lens,
+    abi: logswapLensAbi,
+    functionName: "fLienOf",
+    args: [fPoolShareId(poolId, g), owner],
+  });
+  return { locker, amount, owed };
+}
+
+/**
+ * Lock `amount` of `owner`'s shares for the caller, the locker (`account`). Paid with the owner's
+ * per-id allowance to the locker — the owner first sends `approve(locker, shareId, amount)` on the
+ * F manager ({@link fPoolApproveShares}) — or an operator grant. One locker per (id, owner) while a
+ * lien stands. In practice the lending contract calls `lock` itself; this is the EOA path.
+ */
+export async function fPoolLock(c: LogswapClient, a: { poolId: Hex; owner: Address; amount: bigint; gen?: bigint | number; account: Address }) {
+  const g = a.gen ?? (await fPoolGen(c, a.poolId));
+  return writeFPool0(c, "lock", [fPoolShareId(a.poolId, g), a.owner, a.amount], a.account);
+}
+
+/**
+ * The locker's `unlock`: `amount` of the lien lifted with its share of the lien's dividend, credited
+ * to `to` — the owner (a release) or anyone else (a seizure, the shares moving to `to`). It banks
+ * first. The locker's alone.
+ */
+export async function fPoolUnlock(
+  c: LogswapClient,
+  a: { poolId: Hex; owner: Address; amount: bigint; to: Address; gen?: bigint | number; account: Address },
+) {
+  const g = a.gen ?? (await fPoolGen(c, a.poolId));
+  return writeFPool0(c, "unlock", [fPoolShareId(a.poolId, g), a.owner, a.amount, a.to], a.account);
+}
+
+/** Bank the owner's pending into the lien now — `unlock(id, owner, 0, owner)`: dividends bank lazily. The locker's. */
+export async function fPoolBankLien(c: LogswapClient, a: { poolId: Hex; owner: Address; gen?: bigint | number; account: Address }) {
+  return fPoolUnlock(c, { ...a, amount: 0n, to: a.owner });
+}
+
+/** The owner's per-id allowance to a locker on the F manager's ERC-6909 shares — what `lock` spends. */
+export async function fPoolApproveShares(c: LogswapClient, a: { poolId: Hex; spender: Address; amount: bigint; gen?: bigint | number; account: Address }) {
+  const g = a.gen ?? (await fPoolGen(c, a.poolId));
+  return writeFPool0(c, "approve", [a.spender, fPoolShareId(a.poolId, g), a.amount], a.account);
 }
 
 // ─── internals ────────────────────────────────────────────────────────────────
@@ -788,13 +843,7 @@ export function fPoolGenOfShareId(id: bigint): number {
 
 /** The pool's live generation, one read. */
 export async function fPoolGen(c: LogswapClient, poolId: Hex): Promise<number> {
-  const p = (await c.public.readContract({
-    address: c.addresses.fPoolManager!,
-    abi: fPoolManagerAbi,
-    functionName: "getPool",
-    args: [poolId],
-  } as never)) as { gen: number };
-  return Number(p.gen);
+  return Number((await rawFPool(c, poolId)).gen);
 }
 
 /** The ERC-6909 id carrying claims on a token. Bit 255 clear, so it can never meet a share id. */
@@ -819,12 +868,12 @@ export async function fPoolBundleOf(
   poolId: Hex,
   gen: bigint | number,
 ): Promise<{ supply: bigint; quote: bigint; base: bigint[] }> {
-  const [supply, quote, base] = (await c.public.readContract({
-    address: c.addresses.fPoolManager!,
-    abi: fPoolManagerAbi,
-    functionName: "bundleOf",
+  const [supply, quote, base] = await c.public.readContract({
+    address: c.addresses.lens,
+    abi: logswapLensAbi,
+    functionName: "fBundleOf",
     args: [poolId, BigInt(gen)],
-  } as never)) as readonly [bigint, bigint, readonly bigint[]];
+  });
   return { supply, quote, base: [...base] };
 }
 
@@ -945,8 +994,13 @@ export interface FPoolCreateArgs {
   bases: Address[];
   /** WAD each; must sum to 1e18 — validated here so the revert is readable. */
   weights: bigint[];
-  /** Fixed fee, WAD. The base-for-base fee is pinned at 2φ on-chain. */
-  phi: bigint;
+  /** The swap fee, WAD (`phi` before F version 25). The base-for-base fee is pinned at 2φ on-chain. A curated policy admits only its listed tiers (decisions 059). */
+  swapFee: bigint;
+  /**
+   * The common cap (decisions 061): d = ln(cap price / floor price) in 1e-6 log units, a key field;
+   * 0 or absent is uncapped. From a leverage λ: {@link fPoolCapOfLeverage}.
+   */
+  cap?: number;
   /**
    * Which of the protocol's four the pool is — see {@link FPoolKind}. NOT a key field (decisions
    * 049: the manager knows no kind): it selects the deployment's policy of that kind when `policy`
@@ -1006,11 +1060,13 @@ export interface FPoolKey {
   bases: Address[];
   /** WAD, aligned with `bases`, summing to 1e18. */
   weights: bigint[];
-  phi: bigint;
+  swapFee: bigint;
   /** The policy AT BIRTH — not the live one after a move. */
   policy: Address;
   creator: Address;
   salt: Hex;
+  /** The common cap, d in 1e-6 log units; 0 uncapped (decisions 061). Appended in F version 25: every pool id moved. */
+  cap: number;
 }
 
 const F_POOL_KEY_ABI = [
@@ -1020,10 +1076,11 @@ const F_POOL_KEY_ABI = [
       { name: "quote", type: "address" },
       { name: "bases", type: "address[]" },
       { name: "weights", type: "uint256[]" },
-      { name: "phi", type: "uint256" },
+      { name: "swapFee", type: "uint256" },
       { name: "policy", type: "address" },
       { name: "creator", type: "address" },
       { name: "salt", type: "bytes32" },
+      { name: "cap", type: "uint24" },
     ],
   },
 ] as const;
@@ -1044,10 +1101,11 @@ export function fPoolKeyOf(c: LogswapClient, a: Omit<FPoolCreateArgs, "account">
     quote: a.quote,
     bases,
     weights: companions[0]!,
-    phi: a.phi,
+    swapFee: a.swapFee,
     policy: a.policy ?? fPoolPolicyFor(c, a.kind),
     creator: a.creator,
     salt: a.salt ?? ZERO_SALT,
+    cap: a.cap ?? 0,
   };
 }
 
@@ -1094,21 +1152,22 @@ export async function fPoolKeyOfPool(c: LogswapClient, poolId: Hex, opts: { salt
   });
   const l = logs[0];
   if (!l) throw new Error(`logswap: no FInitialize for F pool ${poolId}`);
-  const a = l.args as { quote: Address; creator: Address; bases: readonly Address[]; weights: readonly bigint[]; phi: bigint; policy: Address };
+  const a = l.args as { quote: Address; creator: Address; bases: readonly Address[]; weights: readonly bigint[]; swapFee: bigint; policy: Address; cap: number };
   const key: FPoolKey = {
     quote: a.quote,
     bases: [...a.bases],
     weights: [...a.weights],
-    phi: a.phi,
+    swapFee: a.swapFee,
     policy: a.policy,
     creator: a.creator,
     salt: opts.salt ?? ZERO_SALT,
+    cap: Number(a.cap),
   };
   if (fPoolIdOfKey(key).toLowerCase() !== poolId.toLowerCase() && opts.salt === undefined) {
     // a pad's salt carries its split (decisions 056): rebuild it from the policy's record with the default nonce
     try {
-      const [creatorShare, burnPerRung] = (await c.public.readContract({ address: a.policy, abi: padPolicyAbi, functionName: "splitOf", args: [poolId] } as never)) as readonly [bigint, bigint, bigint];
-      const padKey = { ...key, salt: padSalt({ creatorShare, burnPerRung }) };
+      const [creatorShare, burnShare] = (await c.public.readContract({ address: a.policy, abi: padPolicyAbi, functionName: "splitOf", args: [poolId] } as never)) as readonly [bigint, bigint, bigint];
+      const padKey = { ...key, salt: padSalt({ creatorShare, burnShare }) };
       if (fPoolIdOfKey(padKey).toLowerCase() === poolId.toLowerCase()) return padKey;
     } catch {
       /* not a pad: fall through to the error */
@@ -1127,11 +1186,38 @@ export async function fPoolKeyOfPool(c: LogswapClient, poolId: Hex, opts: { salt
  * precision (~1e-16 relative) is what a seed needs: any reserve is a legal seed, and the mark
  * the pool derives from it is the one the sponsor meant to within that.
  */
-export function fPoolReserveAt(Lj: bigint, x: bigint): bigint {
-  const e = Math.exp(-Number(x) / 1e18);
+export function fPoolReserveAt(Lj: bigint, x: bigint, k = 0): bigint {
+  // on a capped pool (decisions 061) the mark reads the virtual reserve R̃ = R + c, and the seed
+  // puts c = R·k/(1 − k): so the REAL reserve for a mark is L_j·e^{−x}·(1 − k)
+  const e = Math.exp(-Number(x) / 1e18) * (1 - k);
   return (Lj * BigInt(Math.round(e * 1e18))) / 10n ** 18n;
 }
 
+/**
+ * The seed's cap constant k = e^{Q0/L0 − d} (decisions 061): every leg's phantom is c_j = r_j·k/(1 − k).
+ * 0 on an uncapped pool. Throws when the seed would be priced at or above its cap (Q0/L0 ≥ d), which
+ * the manager refuses.
+ */
+export function fPoolCapK(cap: number, Q0: bigint, L0: bigint): number {
+  if (cap === 0) return 0;
+  const e = Number((Q0 * WAD) / L0) / 1e18 - cap / 1e6;
+  if (e >= 0) throw new Error(`logswap: a seed with Q0/L0 = ${Number((Q0 * WAD) / L0) / 1e18} is at or above its cap d = ${cap / 1e6}`);
+  return Math.exp(e);
+}
+
+/** The cap d (1e-6 log units) for a leverage λ > 1 at the floor: d = ln(λ/(λ − 1)) (decisions 061). λ = 2 puts the cap at twice the floor. */
+export function fPoolCapOfLeverage(lambda: number): number {
+  if (!(lambda > 1)) throw new Error("logswap: leverage must exceed 1 (1 is uncapped: cap 0)");
+  const d = Math.round(Math.log(lambda / (lambda - 1)) * 1e6);
+  if (d < 1 || d > 0xffffff) throw new Error(`logswap: leverage ${lambda} needs a cap outside a uint24 of 1e-6 units`);
+  return d;
+}
+
+/** The leverage at the floor λ = 1/(1 − e^{−d}) for a cap d in 1e-6 log units; Infinity is impossible, 1 is uncapped. */
+export function fPoolLeverageOfCap(cap: number): number {
+  return cap === 0 ? 1 : 1 / (1 - Math.exp(-cap / 1e6));
+}
+
 /**
  * Arm the pool: deposit `r0[j]` of each base plus `Q0` of quote against exposure `L0`. Pass either
  * the reserves outright (`r0`) or the marks the pool should open at (`x0`, converted here with
@@ -1143,7 +1229,12 @@ export async function fPoolSeed(
   c: LogswapClient,
   a: { poolId: Hex; L0: bigint; Q0: bigint; account: Address } & ({ r0: bigint[] } | { x0: bigint[]; weights: bigint[] }),
 ) {
-  const r0 = "r0" in a ? a.r0 : a.x0.map((x, j) => fPoolReserveAt((a.weights[j]! * a.L0) / 10n ** 18n, x));
+  let r0: bigint[];
+  if ("r0" in a) r0 = a.r0;
+  else {
+    const k = fPoolCapK(Number((await rawFPool(c, a.poolId)).cap), a.Q0, a.L0);
+    r0 = a.x0.map((x, j) => fPoolReserveAt((a.weights[j]! * a.L0) / 10n ** 18n, x, k));
+  }
   return writeFPool(c, a.poolId, "seed", [a.L0, r0, a.Q0], a.account);
 }
 
@@ -1205,8 +1296,9 @@ export async function fPoolEmptyingHarvests(c: LogswapClient, poolId: Hex): Prom
  *   and redeems it with {@link fPoolRedeem} / rolls it with {@link fPoolRollIn} (`gen: g`); their
  *   dividends on `g` stay claimable ({@link fPoolClaim} with `gen: g`). {@link fPoolClaimsOf}
  *   lists them;
- * - the pot: `toPayee` to the payee, `protocolCut` to the collector, the rest bought in as dead
- *   shares of `g + 1`; then the burn.
+ * - the pot, all in quote (decisions 057): `toPayee` to the payee, `protocolCut` to the collector,
+ *   `burn` spent buying base at the curve and burning it (the price up, the floor held), and the
+ *   rest into the bid (the floor down). No share is minted; L does not move.
  *
  * A pad's gate is `threshold(gen)` (`PadPolicy.NotGraduated` below it); POL and private carry the
  * authority and send it the whole pot; a public pool refuses (`Refused`). A carried holder with no
@@ -1242,8 +1334,10 @@ export async function fPoolRelaunch(
     account: Address;
   } & ({ r0: bigint[] } | { x0: bigint[]; weights: bigint[] }),
 ) {
-  const [gen, harvests] = await Promise.all([fPoolGen(c, a.poolId), fPoolEmptyingHarvests(c, a.poolId)]);
-  const r0 = "r0" in a ? a.r0 : a.x0.map((x, j) => (a.weights[j]! === 0n ? 0n : fPoolReserveAt((a.weights[j]! * a.L0) / WAD, x)));
+  const [raw, harvests] = await Promise.all([rawFPool(c, a.poolId), fPoolEmptyingHarvests(c, a.poolId)]);
+  const gen = Number(raw.gen);
+  const k = "r0" in a ? 0 : fPoolCapK(Number(raw.cap), a.Q0, a.L0);
+  const r0 = "r0" in a ? a.r0 : a.x0.map((x, j) => (a.weights[j]! === 0n ? 0n : fPoolReserveAt((a.weights[j]! * a.L0) / WAD, x, k)));
   const enc = (functionName: string, args: unknown[]) =>
     encodeFunctionData({ abi: fPoolManagerAbi, functionName, args } as never) as Hex;
   const calls: Hex[] = [
@@ -1334,11 +1428,12 @@ export function fPoolLaunchCalls(
 ): Hex[] {
   const sum = a.weights.reduce((x, y) => x + y, 0n);
   if (sum !== WAD) throw new Error(`logswap: weights sum to ${sum}, expected 1e18`);
-  const given = "r0" in a ? a.r0 : a.x0.map((x, j) => fPoolReserveAt((a.weights[j]! * a.L0) / WAD, x));
+  const k = "r0" in a ? 0 : fPoolCapK(a.cap ?? 0, a.Q0, a.L0);
+  const given = "r0" in a ? a.r0 : a.x0.map((x, j) => fPoolReserveAt((a.weights[j]! * a.L0) / WAD, x, k));
   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.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, policy: a.policy, creator: a.creator, salt: a.salt ?? ZERO_SALT };
+  const key = { quote: a.quote, bases, weights: companions[0]!, swapFee: a.swapFee, policy: a.policy, creator: a.creator, salt: a.salt ?? ZERO_SALT, cap: a.cap ?? 0 };
   const enc = (functionName: string, args: unknown[]) =>
     encodeFunctionData({ abi: fPoolManagerAbi, functionName, args } as never) as Hex;
   const calls: Hex[] = [];
@@ -1703,7 +1798,9 @@ export interface DiscoveredFPool {
   quote: Address;
   bases: Address[];
   weights: bigint[];
-  phi: bigint;
+  swapFee: bigint;
+  /** The common cap, d in 1e-6 log units; 0 uncapped (decisions 061). */
+  cap: number;
   kind: FPoolKind;
   /** The pool's policy AT BIRTH — the contract the key names. The LIVE one is {@link getFPool}'s `policy`: the registry's owner may have moved the pool (046, `PolicyMigrated`). */
   policy: Address;
@@ -1727,7 +1824,7 @@ export interface DiscoveredFPool {
 /**
  * Every F pool ever created, from `Initialize` logs alone — plus one `kind()` read per distinct
  * policy, cached. Possible only because the event carries the full key preimage (bases,
- * weights, phi, policy) — the poolId is a hash and could never be inverted; contracts PR #17
+ * weights, swapFee, policy, cap) — the poolId is a hash and could never be inverted; contracts PR #17
  * exists for exactly this call. With `indexer`, the logs come from it (the node when it fails):
  * a scan from block 0 per call is what made the first load wait on the node.
  */
@@ -1754,7 +1851,7 @@ export async function discoverFPools(
     logs.map(async (l) => {
       const a = l.args as {
         poolId: Hex; quote: Address; creator: Address; bases: readonly Address[];
-        weights: readonly bigint[]; phi: bigint; policy: Address;
+        weights: readonly bigint[]; swapFee: bigint; policy: Address; cap: number;
       };
       const q0 = q0Of.get(a.poolId.toLowerCase());
       const kind = await fPoolKindOfPolicy(c, a.policy); // one read per distinct policy, cached
@@ -1763,7 +1860,8 @@ export async function discoverFPools(
         quote: a.quote,
         bases: [...a.bases],
         weights: [...a.weights],
-        phi: a.phi,
+        swapFee: a.swapFee,
+        cap: Number(a.cap ?? 0),
         kind,
         policy: a.policy,
         creator: a.creator,
@@ -1802,10 +1900,10 @@ export type FPoolRules =
       /** The pot the next graduation needs: `PadPolicy.threshold(gen)`. */
       threshold: bigint;
       pot: bigint;
-      /** This pad's split, recorded at its birth from the key's salt and never changed (decisions 056): the creator's cut of the pot, the protocol's, and the burn per rung. The rest of the pot is bought in. */
+      /** This pad's split, recorded at its birth from the key's salt and never changed (decisions 056, 057): the creator's cut of the pot, the protocol's, and the burn — all fractions of the pot. The rest deepens the bid. */
       creatorShare: bigint;
       protocolShare: bigint;
-      burnPerRung: bigint;
+      burnShare: bigint;
       /** The ranges the collector's policy holds NOW for the pads born after this read: what a new creator may choose. */
       ranges: PadRanges;
     }
@@ -1813,7 +1911,7 @@ export type FPoolRules =
   | { kind: "public"; curated: boolean }
   | { kind: "private"; gateMint: boolean; gateSwap: boolean; operator: Address };
 
-/** The collector's ranges on a pad's creator choices (`PadPolicy`, decisions 056), WAD fractions: of the pot, and of every reserve per rung. */
+/** The collector's ranges on a pad's creator choices (`PadPolicy`, decisions 056, 057), WAD fractions of the pot. */
 export interface PadRanges {
   /** The protocol's share of the pot, recorded into each pad at birth. */
   protocolShare: bigint;
@@ -1827,21 +1925,21 @@ const MAX_U64 = (1n << 64n) - 1n;
 const MAX_U128 = (1n << 128n) - 1n;
 
 /**
- * The salt that carries a pad's split (`PadPolicy.pack`, decisions 056): `creatorShare` in the top 64 bits, `burnPerRung` in
- * the next 64 (WAD fractions), a nonce in the low 128 that tells two otherwise identical pads apart. It is part of the pool's
+ * The salt that carries a pad's split (`PadPolicy.pack`, decisions 056, 057): `creatorShare` in the top 64 bits, `burnShare` in
+ * the next 64 (WAD fractions of the pot), a nonce in the low 128 that tells two otherwise identical pads apart. It is part of the pool's
  * identity, so it is chosen at launch (`FPoolLaunchArgs.salt`) and never changes; the policy refuses a split outside its ranges.
  */
-export function padSalt(s: { creatorShare: bigint; burnPerRung: bigint; nonce?: bigint }): Hex {
+export function padSalt(s: { creatorShare: bigint; burnShare: bigint; nonce?: bigint }): Hex {
   const nonce = s.nonce ?? 0n;
-  if (s.creatorShare < 0n || s.creatorShare > MAX_U64 || s.burnPerRung < 0n || s.burnPerRung > MAX_U64) throw new Error("logswap: a pad's split is a WAD fraction that fits 64 bits");
+  if (s.creatorShare < 0n || s.creatorShare > MAX_U64 || s.burnShare < 0n || s.burnShare > MAX_U64) throw new Error("logswap: a pad's split is a WAD fraction that fits 64 bits");
   if (nonce < 0n || nonce > MAX_U128) throw new Error("logswap: a pad salt's nonce fits 128 bits");
-  return `0x${((s.creatorShare << 192n) | (s.burnPerRung << 128n) | nonce).toString(16).padStart(64, "0")}` as Hex;
+  return `0x${((s.creatorShare << 192n) | (s.burnShare << 128n) | nonce).toString(16).padStart(64, "0")}` as Hex;
 }
 
 /** The inverse of {@link padSalt}. */
-export function padSplitOfSalt(salt: Hex): { creatorShare: bigint; burnPerRung: bigint; nonce: bigint } {
+export function padSplitOfSalt(salt: Hex): { creatorShare: bigint; burnShare: bigint; nonce: bigint } {
   const v = BigInt(salt);
-  return { creatorShare: v >> 192n, burnPerRung: (v >> 128n) & MAX_U64, nonce: v & MAX_U128 };
+  return { creatorShare: v >> 192n, burnShare: (v >> 128n) & MAX_U64, nonce: v & MAX_U128 };
 }
 
 /** The policy's terms for one pool, by its kind. */
@@ -1862,9 +1960,9 @@ export async function getFPoolRules(c: LogswapClient, s: Pick<FPoolState, "poolI
         rd<bigint>(padPolicyAbi, "burnMin"),
         rd<bigint>(padPolicyAbi, "burnMax"),
       ]);
-      const [creatorShare, burnPerRung, protocolShare] = split;
+      const [creatorShare, burnShare, protocolShare] = split;
       const ranges: PadRanges = { protocolShare: protocolNow, creatorShareMin, creatorShareMax, burnMin, burnMax };
-      return { kind: "pad", gen, rung: gen, threshold, pot, creatorShare, protocolShare, burnPerRung, ranges };
+      return { kind: "pad", gen, rung: gen, threshold, pot, creatorShare, protocolShare, burnShare, ranges };
     }
     case "pol": {
       const [keepQuote, minQuoteAtSeed] = await Promise.all([rd<bigint>(polPolicyAbi, "keepQuote"), rd<bigint>(polPolicyAbi, "minQuoteAtSeed")]);
@@ -1952,7 +2050,7 @@ export interface FPolicyTerms {
   carried: Address;
 }
 
-/** Every F pool's state in one lens call (the raw manager struct: quote, phi, authority, kind, seeded, gen, n, Q, L, shares, theta0, bigSigma, harvestedTheta). */
+/** Every F pool's raw state in one lens call (the manager's `Pool` struct: quote, swapFee, policy, seeded, gen, n, restructureBlock, asks, cap, Q, bigSigma, L, shares, refLogFloor). */
 export async function getFPoolsRaw(c: LogswapClient, poolIds: Hex[]): Promise<readonly unknown[]> {
   const { logswapLensAbi } = await import("./generated.js");
   return (await c.public.readContract({ address: c.addresses.lens, abi: logswapLensAbi, functionName: "getFPools", args: [poolIds] } as never)) as readonly unknown[];