@logswap/sdk 0.5.71 → 0.5.72

package/dist/fpool.js

@@ -30,7 +30,7 @@
  * `addresses.router`.
  */
 import { decodeAbiParameters, encodeAbiParameters, encodeFunctionData, erc20Abi, keccak256, toFunctionSelector } 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`,
  * `setLegs`, the names, the fee parameters are `FPoolManager`'s own code. The roles left it for
@@ -52,20 +52,30 @@ const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
 /** The optional questions a policy declared at birth, 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. */
+/**
+ * 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, poolId) {
+    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, poolId) {
-    // 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 = (functionName, args) => c.public.readContract({
-        address: c.addresses.fPoolManager,
-        abi: fPoolManagerAbi,
-        functionName,
-        args,
+    const v = await c.public.readContract({
+        address: c.addresses.lens,
+        abi: logswapLensAbi,
+        functionName: "fPool",
+        args: [poolId],
     });
-    // `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("getPool", [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
@@ -73,45 +83,33 @@ export async function getFPool(c, poolId) {
     // 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("theta", [poolId]) : rd("compositeX", [poolId]),
-        rd("compositeX", [poolId]),
-        Promise.all(idx.map((i) => rd("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),
     };
 }
 const F_KIND_NAMES = ["public", "private", "pol", "pad"];
@@ -154,15 +152,7 @@ export function fPoolPolicyFor(c, kind) {
 }
 /** The policy a pool named in its key — one read; {@link getFPool} carries it too. */
 export async function fPoolPolicyOf(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.policy;
+    return (await rawFPool(c, poolId)).policy;
 }
 /** Read a pool's roles from its policy. `state` saves the `getPool` round trip when already in hand. */
 export async function getFPoolRoles(c, poolId, state) {
@@ -186,18 +176,11 @@ export async function getFPoolRoles(c, poolId, state) {
     return { policy: s.policy, creator, authority, pendingAuthority, operator, pendingOperator, gateMint, gateSwap, maxHarvest };
 }
 export async function describeFPool(c, s) {
-    const rd = (functionName, args = [s.poolId]) => c.public.readContract({
-        address: c.addresses.fPoolManager,
-        abi: fPoolManagerAbi,
-        functionName,
-        args,
-    });
     // 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("unharvested"), rd("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,
@@ -211,11 +194,24 @@ export async function describeFPool(c, s) {
 export function fPoolPriceOf(x, scale = 1) {
     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) {
     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;
 }
 /**
  * All three F swaps go through the ROUTER's `swapExactIn` overload — the same surface as a C
@@ -385,16 +381,63 @@ export async function fPoolClaim(c, a) {
     const gen = a.gen ?? (await fPoolGen(c, a.poolId));
     return writeFPool(c, a.poolId, "claim", [BigInt(gen), a.to ?? a.account], a.account);
 }
-/** A holder's dividend as of now on generation `gen` (the live one by default) — banked plus pending on the current balance. */
+/**
+ * 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, poolId, holder, gen) {
     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],
     });
 }
+/**
+ * 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, poolId, owner, gen) {
+    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, a) {
+    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, a) {
+    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, a) {
+    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, a) {
+    const g = a.gen ?? (await fPoolGen(c, a.poolId));
+    return writeFPool0(c, "approve", [a.spender, fPoolShareId(a.poolId, g), a.amount], a.account);
+}
 // ─── internals ────────────────────────────────────────────────────────────────
 function defaultDeadline() {
     return BigInt(Math.floor(Date.now() / 1000) + 1800);
@@ -529,13 +572,7 @@ export function fPoolGenOfShareId(id) {
 }
 /** The pool's live generation, one read. */
 export async function fPoolGen(c, poolId) {
-    const p = (await c.public.readContract({
-        address: c.addresses.fPoolManager,
-        abi: fPoolManagerAbi,
-        functionName: "getPool",
-        args: [poolId],
-    }));
-    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. */
 export function fPoolClaimId(token) {
@@ -553,12 +590,12 @@ export async function fPoolShareBalance(c, poolId, owner, gen) {
 }
 /** A retired generation's bundle: what is left to redeem — supply, quote, base per leg index. */
 export async function fPoolBundleOf(c, poolId, gen) {
-    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)],
-    }));
+    });
     return { supply, quote, base: [...base] };
 }
 /** A holder's claims on a pool's retired generations — one row per generation still held. */
@@ -678,10 +715,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" },
         ],
     },
 ];
@@ -700,10 +738,11 @@ export function fPoolKeyOf(c, a) {
         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,
     };
 }
 /** Create the pool (no funds move — `seed` arms it). Returns the tx hash; read the id with `fPoolIdOf`. */
@@ -753,16 +792,17 @@ export async function fPoolKeyOfPool(c, poolId, opts = {}) {
         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] }));
-            const padKey = { ...key, salt: padSalt({ creatorShare, burnPerRung }) };
+            const [creatorShare, burnShare] = (await c.public.readContract({ address: a.policy, abi: padPolicyAbi, functionName: "splitOf", args: [poolId] }));
+            const padKey = { ...key, salt: padSalt({ creatorShare, burnShare }) };
             if (fPoolIdOfKey(padKey).toLowerCase() === poolId.toLowerCase())
                 return padKey;
         }
@@ -782,10 +822,38 @@ export async function fPoolKeyOfPool(c, poolId, opts = {}) {
  * 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, x) {
-    const e = Math.exp(-Number(x) / 1e18);
+export function fPoolReserveAt(Lj, x, k = 0) {
+    // 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, Q0, L0) {
+    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) {
+    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) {
+    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
@@ -794,7 +862,13 @@ export function fPoolReserveAt(Lj, x) {
  * {@link sortFPoolLegs} on (bases, weights, x0) together when building forms.
  */
 export async function fPoolSeed(c, a) {
-    const r0 = "r0" in a ? a.r0 : a.x0.map((x, j) => fPoolReserveAt((a.weights[j] * a.L0) / 10n ** 18n, x));
+    let r0;
+    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);
 }
 /**
@@ -855,8 +929,9 @@ export async function fPoolEmptyingHarvests(c, poolId) {
  *   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
@@ -878,8 +953,10 @@ export async function fPoolRegenerate(c, a) {
  * 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)]);
-    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, args) => encodeFunctionData({ abi: fPoolManagerAbi, functionName, args });
     const calls = [
         ...harvests.map((amount) => enc("harvest", [a.poolId, amount, a.account])),
@@ -905,13 +982,14 @@ export function fPoolLaunchCalls(poolId, a) {
     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, args) => encodeFunctionData({ abi: fPoolManagerAbi, functionName, args });
     const calls = [];
     if (!a.initialized)
@@ -1229,7 +1307,7 @@ export async function fPoolTransferShares(c, a) {
 /**
  * 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.
  */
@@ -1257,7 +1335,8 @@ export async function discoverFPools(c, opts = {}) {
             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,
@@ -1271,22 +1350,22 @@ export async function discoverFPools(c, opts = {}) {
 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) {
     const nonce = s.nonce ?? 0n;
-    if (s.creatorShare < 0n || s.creatorShare > MAX_U64 || s.burnPerRung < 0n || s.burnPerRung > MAX_U64)
+    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")}`;
+    return `0x${((s.creatorShare << 192n) | (s.burnShare << 128n) | nonce).toString(16).padStart(64, "0")}`;
 }
 /** The inverse of {@link padSalt}. */
 export function padSplitOfSalt(salt) {
     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. */
 export async function getFPoolRules(c, s, roles) {
@@ -1305,9 +1384,9 @@ export async function getFPoolRules(c, s, roles) {
                 rd(padPolicyAbi, "burnMin"),
                 rd(padPolicyAbi, "burnMax"),
             ]);
-            const [creatorShare, burnPerRung, protocolShare] = split;
+            const [creatorShare, burnShare, protocolShare] = split;
             const ranges = { 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(polPolicyAbi, "keepQuote"), rd(polPolicyAbi, "minQuoteAtSeed")]);
@@ -1370,7 +1449,7 @@ export async function fPoolShareHolders(c, poolIdHex, opts = {}) {
         .map(([holder, shares]) => ({ holder: holder, shares }))
         .sort((a, b) => (b.shares > a.shares ? 1 : -1));
 }
-/** 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, poolIds) {
     const { logswapLensAbi } = await import("./generated.js");
     return (await c.public.readContract({ address: c.addresses.lens, abi: logswapLensAbi, functionName: "getFPools", args: [poolIds] }));