@logswap/sdk 0.5.68 → 0.5.70

package/src/fpool.ts

@@ -30,7 +30,7 @@
  * `addresses.router`.
  */
 
-import { encodeAbiParameters, encodeFunctionData, keccak256, toFunctionSelector, type Address, type Hash, type Hex } from "viem";
+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";
 
 /**
@@ -42,8 +42,8 @@ import { fPoolManagerAbi, logswapRouterAbi, padPolicyAbi, polPolicyAbi, policyRe
  */
 export { fPoolManagerAbi, padPolicyAbi, polPolicyAbi, privatePolicyAbi, publicPolicyAbi };
 /**
- * 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
+ * What every protocol policy shares (`FPolicyBase`): the roles and their handover and the
+ * `maxHarvest` readout (a harvest has no cut, decisions 056). `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 fPolicyBaseAbi = polPolicyAbi;
@@ -1079,7 +1079,7 @@ export async function fPoolIdOf(c: LogswapClient, a: Omit<FPoolCreateArgs, "acco
 /**
  * Rebuild a live pool's KEY from its id: the `FInitialize` log carries every field but the salt,
  * which is taken from `opts.salt` (zero by default — every pool the SDK's create flow makes
- * without naming one). The result is checked against the id, so a wrong salt throws rather than
+ * without naming one; a pad's carries its split, so it is rebuilt from the policy's record with nonce 0 — pass `opts.salt` for another nonce). The result is checked against the id, so a wrong salt throws rather than
  * returning a key that names another pool. What {@link fPoolMigrate} needs when handed an id.
  */
 export async function fPoolKeyOfPool(c: LogswapClient, poolId: Hex, opts: { salt?: Hex; fromBlock?: bigint } = {}): Promise<FPoolKey> {
@@ -1104,6 +1104,16 @@ export async function fPoolKeyOfPool(c: LogswapClient, poolId: Hex, opts: { salt
     creator: a.creator,
     salt: opts.salt ?? ZERO_SALT,
   };
+  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 }) };
+      if (fPoolIdOfKey(padKey).toLowerCase() === poolId.toLowerCase()) return padKey;
+    } catch {
+      /* not a pad: fall through to the error */
+    }
+  }
   if (fPoolIdOfKey(key).toLowerCase() !== poolId.toLowerCase()) {
     throw new Error(`logswap: F pool ${poolId} was not born with salt ${key.salt} — pass its salt, or its whole key`);
   }
@@ -1252,6 +1262,29 @@ export const DEAD_ADDRESS: Address = "0x000000000000000000000000000000000000dEaD
 /** The manager's `MIN_SHARES`: the seed mints this much to 0xdead on every pool, the rest to the seeder — or, on a pad, to 0xdead too. */
 export const F_MIN_SHARES = 1000n;
 
+/**
+ * One genesis transaction: a swap the creator sends right after the seed, inside the launch's
+ * `multicall`. A `buy` spends `amountIn` of quote for leg `j` (an index into `bases` AS GIVEN); a
+ * `sell` spends `amountIn` of that leg for quote. The creator pays and is paid — the manager settles
+ * to its sender — so a `recipient` is paid by an ERC-20 transfer of the row's output
+ * ({@link fPoolGenesisTransfers}); without one the output stays with the creator.
+ */
+export interface FPoolGenesisRow {
+  side: "buy" | "sell";
+  j: number;
+  amountIn: bigint;
+  /** Defaults to 0. With a `recipient`, {@link fPoolLaunch} pins it to the simulated output, which is what the transfer pays. */
+  minOut?: bigint;
+  recipient?: Address;
+}
+
+/** An ERC-20 transfer owed to a genesis recipient: one per (token, recipient), rows summed. */
+export interface FPoolGenesisTransfer {
+  token: Address;
+  to: Address;
+  amount: bigint;
+}
+
 export interface FPoolLaunchArgs extends Omit<FPoolCreateArgs, "account"> {
   L0: bigint;
   /** Quote the seed pulls. A pad seeds at 0 — pure float, a resting ask, nothing raised. */
@@ -1264,6 +1297,18 @@ export interface FPoolLaunchArgs extends Omit<FPoolCreateArgs, "account"> {
    * this buy — they are one transaction — so `minOut` is safe at its default of 0.
    */
   openBuy?: { j: number; amountIn: bigint; minOut?: bigint };
+  /**
+   * The genesis transactions: an ordered list of swaps right after the seed, each with an optional
+   * recipient ({@link FPoolGenesisRow}). The same batch as `openBuy`, which stays as the one-buy
+   * case and runs first when both are given. See `specs/f-pools/opening.md`.
+   */
+  openBatch?: FPoolGenesisRow[];
+  /**
+   * How a row's recipient is paid. `auto` (default): in the launch's own transaction when the
+   * wallet batches atomically (EIP-5792), else left to {@link fPoolSendGenesisTransfers};
+   * `followup`: always left to it. Ignored when no row names a recipient.
+   */
+  deliver?: "auto" | "followup";
   /** The pool's label (≤ 31 bytes of UTF-8) — the policy's word (049), written right after the batch by {@link fPoolLaunch}; not in the batch. */
   name?: string;
   /**
@@ -1301,10 +1346,10 @@ export function fPoolLaunchCalls(
   calls.push(enc("seed", [poolId, a.L0, companions[1]!, a.Q0]));
   // gen 0 by construction: a launch is the pool's FIRST seed — a relaunch is `fPoolRelaunch`.
   // No transfer to 0xdead: on a pad `seed` mints every share there itself.
-  if (a.openBuy) {
-    const j = bases.indexOf(a.bases[a.openBuy.j]!);
-    if (j < 0) throw new Error(`logswap: openBuy.j = ${a.openBuy.j} is not a leg`);
-    calls.push(enc("swapQuoteIn", [poolId, BigInt(j), a.openBuy.amountIn, a.openBuy.minOut ?? 0n, a.account]));
+  for (const row of fPoolGenesisRows(a)) {
+    const j = bases.indexOf(a.bases[row.j]!);
+    if (j < 0) throw new Error(`logswap: genesis row j = ${row.j} is not a leg`);
+    calls.push(enc(row.side === "buy" ? "swapQuoteIn" : "swapBaseIn", [poolId, BigInt(j), row.amountIn, row.minOut ?? 0n, a.account]));
   }
   // the name, the desk's gates and its list are the POLICY's, not the
   // manager's: they cannot ride in this batch — `fPoolLaunch` and `fPoolDeskOpening` send them
@@ -1313,6 +1358,87 @@ export function fPoolLaunchCalls(
   return calls;
 }
 
+/** The genesis rows in the order they run: `openBuy` first when given, then `openBatch`. Legs as given. */
+export function fPoolGenesisRows(a: Pick<FPoolLaunchArgs, "openBuy" | "openBatch">): FPoolGenesisRow[] {
+  return [...(a.openBuy ? [{ side: "buy" as const, ...a.openBuy }] : []), ...(a.openBatch ?? [])];
+}
+
+/**
+ * What each genesis row returned, read by simulating the launch's `multicall` on the chain — the
+ * contract's own rounding, no re-implementation. Exact at send time: the pool is new, and nothing
+ * can trade between the seed and the rows. Needs the creator's funds and allowances, as the launch
+ * does. One output per row, in {@link fPoolGenesisRows} order: base for a buy, quote for a sell.
+ */
+export async function fPoolGenesisOutputs(
+  c: LogswapClient,
+  poolId: Hex,
+  a: FPoolLaunchArgs & ({ r0: bigint[] } | { x0: bigint[] }),
+): Promise<bigint[]> {
+  const rows = fPoolGenesisRows(a);
+  if (rows.length === 0) return [];
+  const calls = fPoolLaunchCalls(poolId, a);
+  const { result } = await c.public.simulateContract({
+    address: c.addresses.fPoolManager!,
+    abi: fPoolManagerAbi,
+    functionName: "multicall",
+    args: [calls],
+    account: signerFor(c, a.account),
+  } as never);
+  const results = result as readonly Hex[];
+  const first = (a.initialized ? 0 : 1) + 1; // [initialize] · seed · rows
+  return rows.map((_, i) => decodeAbiParameters([{ type: "uint256" }], results[first + i]!)[0] as bigint);
+}
+
+/**
+ * The transfers that pay the recipients: each row's output (`outs`, aligned with
+ * {@link fPoolGenesisRows}) to its `recipient`, summed per (token, recipient), zero amounts dropped.
+ * The token is the leg's base for a buy and the quote for a sell. Pure.
+ */
+export function fPoolGenesisTransfers(
+  a: Pick<FPoolLaunchArgs, "quote" | "bases" | "openBuy" | "openBatch">,
+  outs: bigint[],
+): FPoolGenesisTransfer[] {
+  const out = new Map<string, FPoolGenesisTransfer>();
+  fPoolGenesisRows(a).forEach((row, i) => {
+    if (!row.recipient || !outs[i]) return;
+    const token = row.side === "buy" ? a.bases[row.j]! : a.quote;
+    const k = `${token.toLowerCase()}:${row.recipient.toLowerCase()}`;
+    const t = out.get(k);
+    if (t) t.amount += outs[i]!;
+    else out.set(k, { token, to: row.recipient, amount: outs[i]! });
+  });
+  return [...out.values()];
+}
+
+/** Pay genesis recipients with plain ERC-20 transfers, one transaction each, in order. For a launch that did not deliver itself. */
+export async function fPoolSendGenesisTransfers(c: LogswapClient, a: { transfers: FPoolGenesisTransfer[]; account: Address }): Promise<Hash[]> {
+  const wallet = requireWallet(c);
+  const hashes: Hash[] = [];
+  for (const t of a.transfers) {
+    const { request } = await c.public.simulateContract({
+      address: t.token,
+      abi: erc20Abi,
+      functionName: "transfer",
+      args: [t.to, t.amount],
+      account: signerFor(c, a.account),
+    } as never);
+    hashes.push(await wallet.writeContract(request as never));
+  }
+  return hashes;
+}
+
+/** Whether the wallet runs a batch of calls atomically (EIP-5792 `atomic` capability), on the client's chain. A wallet without it, or one that errors, says no. */
+export async function fPoolWalletBatchesAtomically(c: LogswapClient, account: Address): Promise<boolean> {
+  try {
+    const wallet = requireWallet(c);
+    const chainId = wallet.chain?.id;
+    const caps = (await wallet.getCapabilities({ account, chainId })) as { atomic?: { status?: string } };
+    return caps?.atomic?.status === "supported" || caps?.atomic?.status === "ready";
+  } catch {
+    return false;
+  }
+}
+
 /**
  * The desk's opening posture, on its policy: gated minting, the creator a
  * minter. No appointment: the authority is the operator until one is appointed.
@@ -1346,13 +1472,42 @@ export async function fPoolDeskOpening(c: LogswapClient, a: { poolId: Hex; accou
 export async function fPoolLaunch(
   c: LogswapClient,
   a: FPoolLaunchArgs & ({ r0: bigint[] } | { x0: bigint[] }),
-): Promise<{ hash: Hash; poolId: Hex }> {
+): Promise<{ hash: Hash; poolId: Hex; transfers: FPoolGenesisTransfer[]; delivered: boolean }> {
   const poolId = await fPoolIdOf(c, a);
   const policy = a.policy ?? fPoolPolicyFor(c, a.kind);
-  const calls = fPoolLaunchCalls(poolId, { ...a, policy });
-  const hash = await writeFPool0(c, "multicall", [calls], a.account);
+  let args = { ...a, policy };
+  // With recipients, each row's minOut is pinned to its simulated output and the transfers pay
+  // exactly that: a row that returns less reverts the launch, a wei of surplus stays with the creator.
+  let transfers: FPoolGenesisTransfer[] = [];
+  const rows = fPoolGenesisRows(a);
+  if (rows.some((r) => r.recipient)) {
+    const outs = await fPoolGenesisOutputs(c, poolId, args);
+    args = { ...args, openBuy: undefined, openBatch: rows.map((r, i) => ({ ...r, minOut: outs[i]! })) };
+    transfers = fPoolGenesisTransfers(args, outs);
+  }
+  const calls = fPoolLaunchCalls(poolId, args);
+  let hash: Hash;
+  let delivered = transfers.length === 0;
+  if (transfers.length > 0 && a.deliver !== "followup" && (await fPoolWalletBatchesAtomically(c, a.account))) {
+    const wallet = requireWallet(c);
+    const { id } = await wallet.sendCalls({
+      account: signerFor(c, a.account),
+      forceAtomic: true,
+      calls: [
+        { to: c.addresses.fPoolManager!, data: encodeFunctionData({ abi: fPoolManagerAbi, functionName: "multicall", args: [calls] } as never) },
+        ...transfers.map((t) => ({ to: t.token, data: encodeFunctionData({ abi: erc20Abi, functionName: "transfer", args: [t.to, t.amount] }) })),
+      ],
+    } as never);
+    const status = await wallet.waitForCallsStatus({ id });
+    const receipt = status.receipts?.[0];
+    if (status.status !== "success" || !receipt) throw new Error("logswap: the launch batch did not succeed — nothing was created");
+    hash = receipt.transactionHash;
+    delivered = true;
+  } else {
+    hash = await writeFPool0(c, "multicall", [calls], a.account);
+  }
   if (a.name) await fPoolSetName(c, { poolId, name: a.name, account: a.account, policy });
-  return { hash, poolId };
+  return { hash, poolId, transfers, delivered };
 }
 
 // ─── the roles, on the policy ─────────────────────────────────────────────
@@ -1640,7 +1795,6 @@ export interface FPoolControlled {
 export type FPoolRules =
   | {
       kind: "pad";
-      harvestCut: bigint;
       /** The pad's graduation count: the pool's generation (F version 21 — `PadPolicy.rung` is gone). */
       gen: number;
       /** @deprecated Equal to {@link gen} since F version 21, kept for callers; read `gen`. */
@@ -1648,43 +1802,81 @@ 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. */
       creatorShare: bigint;
       protocolShare: bigint;
       burnPerRung: bigint;
+      /** The ranges the collector's policy holds NOW for the pads born after this read: what a new creator may choose. */
+      ranges: PadRanges;
     }
-  | { kind: "pol"; harvestCut: bigint; keepQuote: bigint; minQuoteAtSeed: bigint }
-  | { kind: "public"; harvestCut: bigint; curated: boolean }
-  | { kind: "private"; harvestCut: bigint; gateMint: boolean; gateSwap: boolean; operator: Address };
+  | { kind: "pol"; keepQuote: bigint; minQuoteAtSeed: bigint }
+  | { 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. */
+export interface PadRanges {
+  /** The protocol's share of the pot, recorded into each pad at birth. */
+  protocolShare: bigint;
+  creatorShareMin: bigint;
+  creatorShareMax: bigint;
+  burnMin: bigint;
+  burnMax: bigint;
+}
+
+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
+ * 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 {
+  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 (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;
+}
+
+/** The inverse of {@link padSalt}. */
+export function padSplitOfSalt(salt: Hex): { creatorShare: bigint; burnPerRung: bigint; nonce: bigint } {
+  const v = BigInt(salt);
+  return { creatorShare: v >> 192n, burnPerRung: (v >> 128n) & MAX_U64, nonce: v & MAX_U128 };
+}
 
 /** 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.policy, abi, functionName, args } as never) as Promise<T>;
-  const harvestCut = await rd<bigint>(fPolicyBaseAbi, "harvestCut");
   switch (s.kind) {
     case "pad": {
       // the rung is the manager's generation (F version 21): a move carries it, nothing to ask the policy
       const gen = s.gen;
-      const [creatorShare, protocolShare, burnPerRung, pot, threshold] = await Promise.all([
-        rd<bigint>(padPolicyAbi, "creatorShare"),
-        rd<bigint>(padPolicyAbi, "protocolShare"),
-        rd<bigint>(padPolicyAbi, "burnPerRung"),
+      const [split, pot, threshold, protocolNow, creatorShareMin, creatorShareMax, burnMin, burnMax] = await Promise.all([
+        rd<readonly [bigint, bigint, bigint]>(padPolicyAbi, "splitOf", [s.poolId]),
         fPoolDividendOf(c, s.poolId, DEAD_ADDRESS, gen),
         rd<bigint>(padPolicyAbi, "threshold", [BigInt(gen)]),
+        rd<bigint>(padPolicyAbi, "protocolShare"),
+        rd<bigint>(padPolicyAbi, "creatorShareMin"),
+        rd<bigint>(padPolicyAbi, "creatorShareMax"),
+        rd<bigint>(padPolicyAbi, "burnMin"),
+        rd<bigint>(padPolicyAbi, "burnMax"),
       ]);
-      return { kind: "pad", harvestCut, gen, rung: gen, threshold, pot, creatorShare, protocolShare, burnPerRung };
+      const [creatorShare, burnPerRung, protocolShare] = split;
+      const ranges: PadRanges = { protocolShare: protocolNow, creatorShareMin, creatorShareMax, burnMin, burnMax };
+      return { kind: "pad", gen, rung: gen, threshold, pot, creatorShare, protocolShare, burnPerRung, ranges };
     }
     case "pol": {
       const [keepQuote, minQuoteAtSeed] = await Promise.all([rd<bigint>(polPolicyAbi, "keepQuote"), rd<bigint>(polPolicyAbi, "minQuoteAtSeed")]);
-      return { kind: "pol", harvestCut, keepQuote, minQuoteAtSeed };
+      return { kind: "pol", keepQuote, minQuoteAtSeed };
     }
     case "public": {
       const curated = await rd<boolean>(publicPolicyAbi, "curated");
-      return { kind: "public", harvestCut, curated };
+      return { kind: "public", curated };
     }
     case "private": {
       const r = roles ?? (await getFPoolRoles(c, s.poolId, s));
-      return { kind: "private", harvestCut, gateMint: r.gateMint, gateSwap: r.gateSwap, operator: fPoolOperatorOf(r) };
+      return { kind: "private", gateMint: r.gateMint, gateSwap: r.gateSwap, operator: fPoolOperatorOf(r) };
     }
   }
 }
@@ -1753,8 +1945,7 @@ export async function fPoolShareHolders(
 }
 
 /**
- * What a policy answers `onRegenerate` with (and `onHarvest`'s split, the first four words):
- * `IFPolicy.Terms`. `carried` is F version 21's fifth word — the holder the next generation
+ * What a policy answers `onRegenerate` with: `IFPolicy.Terms`. `carried` is F version 21's fifth word — the holder the next generation
  * carries beside the dead shares; the reply is exactly 160 bytes.
  */
 export interface FPolicyTerms {