@logswap/sdk 0.5.75 → 0.5.76

package/src/views.ts

@@ -0,0 +1,485 @@
+/**
+ * views.ts — the indexer's derived views (indexing phase 2, logswap-be `devnet/VIEWS.md`).
+ *
+ * The indexer records events and the snapshotter samples state; these views join the two in
+ * Postgres: holders, a wallet's positions and flows, per-swap volume and fee, price points and
+ * candles, TVL by the hour, the pools table's 24 h / 7 d figures, the generation steps and pad
+ * status, protocol revenue by day, and who did each routed action. Each reader returns typed rows:
+ *
+ * - **amounts** (Postgres `numeric`, GraphQL BigFloat strings) as `bigint`. The views floor every
+ *   amount they compute, so the integer part is the value;
+ * - **prices, APYs, progress** (`double precision`) as `number`. `priceRaw` is quote wei per base
+ *   wei: scale by 10^(baseDecimals − quoteDecimals) to display;
+ * - **times** as unix seconds (`number`), **addresses** checksummed, pool ids lowercase `0x…`.
+ *
+ * A view is a cache like any indexed table: the readers throw when the indexer cannot answer, and
+ * the SDK functions that use them ({@link holdingsOf}, {@link swapFees}, {@link fPoolShareHolders})
+ * keep their node path as the fallback.
+ */
+import { getAddress, type Address, type Hex } from "viem";
+import { gql } from "./indexer.js";
+
+const PAGE = 1000; // postgraphile's cap
+const MAX_PAGES = 200;
+const PARALLEL_PAGES = 8;
+
+/** What a view query takes: postgraphile's `condition` (equality), `filter` (the connection-filter plugin's operators), an `orderBy` of the view's enum names, a row cap. */
+export interface ViewQuery {
+  condition?: Record<string, unknown>;
+  filter?: Record<string, unknown>;
+  /** e.g. `["BLOCK_NUMBER_ASC"]`, `["VOLUME_24H_DESC"]`: the column's CONSTANT_CASE name and a direction. */
+  orderBy?: string[];
+  /** At most this many rows (one page up to 1000). All rows when omitted. */
+  first?: number;
+  signal?: AbortSignal;
+}
+
+type Row = Record<string, unknown>;
+
+/** Every row of a view, paged by offset (a view has no primary key to page a cursor on). */
+async function viewRows(url: string, field: string, type: string, selection: string, q: ViewQuery): Promise<Row[]> {
+  for (const o of q.orderBy ?? []) if (!/^[A-Z0-9_]+$/.test(o)) throw new Error(`views: orderBy ${JSON.stringify(o)} is not an enum name`);
+  const hasCondition = q.condition !== undefined && Object.keys(q.condition).length > 0;
+  const hasFilter = q.filter !== undefined && Object.keys(q.filter).length > 0;
+  const pageSize = Math.min(q.first ?? PAGE, PAGE);
+  // postgraphile refuses a null or empty condition/filter: each appears only when it has content
+  const decl = `$offset: Int${hasCondition ? `, $condition: ${type}Condition` : ""}${hasFilter ? `, $filter: ${type}Filter` : ""}`;
+  const args = [
+    `first: ${pageSize}`,
+    "offset: $offset",
+    q.orderBy?.length ? `orderBy: [${q.orderBy.join(", ")}]` : "",
+    hasCondition ? "condition: $condition" : "",
+    hasFilter ? "filter: $filter" : "",
+  ].filter(Boolean).join(", ");
+  const query = `query View(${decl}) { ${field}(${args}) { totalCount nodes { ${selection} } } }`;
+  type Conn = { totalCount: number; nodes: Row[] };
+  const page = async (offset: number): Promise<Conn> =>
+    (await gql<Record<string, Conn>>(url, query, { offset, ...(hasCondition ? { condition: q.condition } : {}), ...(hasFilter ? { filter: q.filter } : {}) }, q.signal))[field]!;
+  const first = await page(0);
+  const rows = [...first.nodes];
+  if (q.first === undefined && first.totalCount > first.nodes.length) {
+    const pages = Math.ceil(first.totalCount / PAGE);
+    if (pages > MAX_PAGES) throw new Error(`views: ${field} has more than ${PAGE * MAX_PAGES} rows; narrow the query`);
+    const offsets = Array.from({ length: pages - 1 }, (_, i) => (i + 1) * PAGE);
+    for (let i = 0; i < offsets.length; i += PARALLEL_PAGES) {
+      for (const g of await Promise.all(offsets.slice(i, i + PARALLEL_PAGES).map(page))) rows.push(...g.nodes);
+    }
+  } else if (q.first !== undefined && q.first > PAGE) {
+    // a cap above one page: the next pages up to it
+    for (let offset = PAGE; offset < Math.min(q.first, first.totalCount); offset += PAGE) rows.push(...(await page(offset)).nodes);
+    rows.length = Math.min(rows.length, q.first);
+  }
+  return rows;
+}
+
+// ─── column parsers ──────────────────────────────────────────────────────────
+
+/** A numeric / bigint column (BigFloat or BigInt string, or a number) → bigint; the integer part. */
+function big(v: unknown): bigint {
+  if (typeof v === "bigint") return v;
+  if (typeof v === "number") return BigInt(Math.trunc(v));
+  if (typeof v !== "string" || v === "") throw new Error(`views: not a number: ${JSON.stringify(v)}`);
+  return BigInt(v.split(".")[0]!);
+}
+const bigOr = (v: unknown): bigint | null => (v === null || v === undefined ? null : big(v));
+const num = (v: unknown): number => Number(v);
+const numOr = (v: unknown): number | null => (v === null || v === undefined ? null : Number(v));
+const intOr = (v: unknown): number | null => (v === null || v === undefined ? null : Number(v));
+const addr = (v: unknown): Address => getAddress(String(v));
+const addrOr = (v: unknown): Address | null => (v === null || v === undefined ? null : getAddress(String(v)));
+const secs = (v: unknown): number => Date.parse(String(v)) / 1000;
+const secsOr = (v: unknown): number | null => (v === null || v === undefined ? null : secs(v));
+const hex = (v: unknown): Hex => String(v).toLowerCase() as Hex;
+const addrs = (v: unknown): Address[] => ((v as unknown[] | null) ?? []).map(addr);
+
+export type Side = "C" | "F";
+
+// ─── pool_directory ──────────────────────────────────────────────────────────
+
+/** A pool of either manager: C markets are kind `market`; F pools carry their policy's registry name (`public`, `private`, `pol`, `pad`). */
+export interface PoolDirectoryRow {
+  side: Side;
+  poolId: Hex;
+  manager: Address;
+  kind: string;
+  quote: Address;
+  bases: Address[];
+  swapFee: bigint;
+  /** C only. */
+  tickSpacing: bigint | null;
+  /** F only. */
+  policy: Address | null;
+  creator: Address | null;
+  birthBlock: bigint;
+  birthTime: number;
+  /** F only: the pool's share-id key (the id's bits above the generation). */
+  shareKey: bigint | null;
+}
+export async function poolDirectory(url: string, q: ViewQuery = {}): Promise<PoolDirectoryRow[]> {
+  const rows = await viewRows(url, "allPoolDirectories", "PoolDirectory", "side poolId manager kind quote bases swapFee tickSpacing policy creator birthBlock birthTime shareKey", q);
+  return rows.map((r) => ({
+    side: r.side as Side, poolId: hex(r.poolId), manager: addr(r.manager), kind: String(r.kind), quote: addr(r.quote), bases: addrs(r.bases),
+    swapFee: big(r.swapFee), tickSpacing: bigOr(r.tickSpacing), policy: addrOr(r.policy), creator: addrOr(r.creator),
+    birthBlock: big(r.birthBlock), birthTime: secs(r.birthTime), shareKey: bigOr(r.shareKey),
+  }));
+}
+
+// ─── event_user ──────────────────────────────────────────────────────────────
+
+/** A manager event and who did it: the router's caller when the transaction went through the router (`viaRouter`), else the address the event names (`actor`). */
+export interface EventUserRow {
+  side: Side;
+  /** `Swap` `Mint` `Burn` `Update` `Claim` (C); `FSwap` `FMint` `FBurn` `Harvest` `DividendClaimed` `Redeem` (F). */
+  event: string;
+  poolId: Hex;
+  actor: Address;
+  viaRouter: boolean;
+  user: Address;
+  txHash: Hex;
+  logIndex: number;
+  blockNumber: bigint;
+  blockTimestamp: number;
+  manager: Address;
+}
+export async function eventUsers(url: string, q: ViewQuery = {}): Promise<EventUserRow[]> {
+  const rows = await viewRows(url, "allEventUsers", "EventUser", "side event poolId actor viaRouter user txHash logIndex blockNumber blockTimestamp manager", q);
+  return rows.map((r) => ({
+    side: r.side as Side, event: String(r.event), poolId: hex(r.poolId), actor: addr(r.actor), viaRouter: Boolean(r.viaRouter), user: addr(r.user),
+    txHash: hex(r.txHash), logIndex: num(r.logIndex), blockNumber: big(r.blockNumber), blockTimestamp: secs(r.blockTimestamp), manager: addr(r.manager),
+  }));
+}
+
+// ─── pool_holder ─────────────────────────────────────────────────────────────
+
+/** A current ERC-6909 balance: C ids resolve to their class (floor, cap), F ids to their pool and generation. C's backstop lock is held by address(0) (`isBackstop`), F's dead shares by 0xdead (`isDead`). */
+export interface PoolHolderRow {
+  side: Side;
+  manager: Address;
+  id: bigint;
+  poolId: Hex | null;
+  /** F only. */
+  gen: number | null;
+  /** C only. */
+  floor: bigint | null;
+  cap: bigint | null;
+  capped: boolean | null;
+  holder: Address;
+  balance: bigint;
+  isBackstop: boolean;
+  isDead: boolean;
+}
+export async function poolHolders(url: string, q: ViewQuery = {}): Promise<PoolHolderRow[]> {
+  const rows = await viewRows(url, "allPoolHolders", "PoolHolder", "side manager id poolId gen floor cap capped holder balance isBackstop isDead", q);
+  return rows.map((r) => ({
+    side: r.side as Side, manager: addr(r.manager), id: big(r.id), poolId: r.poolId == null ? null : hex(r.poolId), gen: intOr(r.gen),
+    floor: bigOr(r.floor), cap: bigOr(r.cap), capped: r.capped == null ? null : Boolean(r.capped),
+    holder: addr(r.holder), balance: big(r.balance), isBackstop: Boolean(r.isBackstop), isDead: Boolean(r.isDead),
+  }));
+}
+
+// ─── wallet_position ─────────────────────────────────────────────────────────
+
+/** A wallet's holding (backstop and dead excluded). `valueQuote`: an F share of the live generation at the latest snapshot's share value, a retired one at its bundle's quote per share; NULL for C (a lens read: {@link legsOf}). */
+export interface WalletPositionRow {
+  side: Side;
+  manager: Address;
+  wallet: Address;
+  poolId: Hex | null;
+  kind: string | null;
+  quote: Address | null;
+  bases: Address[];
+  id: bigint;
+  gen: number | null;
+  floor: bigint | null;
+  cap: bigint | null;
+  capped: boolean | null;
+  shares: bigint;
+  valueQuote: bigint | null;
+  /** `live` / `retired` / `unknown` (F), `class` (C). */
+  status: string;
+  valuedAtBlock: bigint | null;
+}
+export async function walletPositions(url: string, q: ViewQuery = {}): Promise<WalletPositionRow[]> {
+  const rows = await viewRows(url, "allWalletPositions", "WalletPosition", "side manager wallet poolId kind quote bases id gen floor cap capped shares valueQuote status valuedAtBlock", q);
+  return rows.map((r) => ({
+    side: r.side as Side, manager: addr(r.manager), wallet: addr(r.wallet), poolId: r.poolId == null ? null : hex(r.poolId), kind: r.kind == null ? null : String(r.kind),
+    quote: addrOr(r.quote), bases: addrs(r.bases), id: big(r.id), gen: intOr(r.gen), floor: bigOr(r.floor), cap: bigOr(r.cap),
+    capped: r.capped == null ? null : Boolean(r.capped), shares: big(r.shares), valueQuote: bigOr(r.valueQuote), status: String(r.status), valuedAtBlock: bigOr(r.valuedAtBlock),
+  }));
+}
+
+// ─── wallet_pool_flow ────────────────────────────────────────────────────────
+
+/** A wallet's flows in a pool, from its own events: what it put in and took out, fees and dividends realised. F mints and burns carry the quote leg only. C `Update` is not counted (it repeats its Burn and Mint). */
+export interface WalletPoolFlowRow {
+  side: Side;
+  manager: Address;
+  wallet: Address;
+  poolId: Hex;
+  baseIn: bigint;
+  quoteIn: bigint;
+  baseOut: bigint;
+  quoteOut: bigint;
+  feesRealised: bigint;
+  dividendsClaimed: bigint;
+  redeemedQuote: bigint;
+  entries: number;
+  exits: number;
+  firstTime: number;
+  lastTime: number;
+}
+export async function walletPoolFlows(url: string, q: ViewQuery = {}): Promise<WalletPoolFlowRow[]> {
+  const rows = await viewRows(url, "allWalletPoolFlows", "WalletPoolFlow", "side manager wallet poolId baseIn quoteIn baseOut quoteOut feesRealised dividendsClaimed redeemedQuote entries exits firstTime lastTime", q);
+  return rows.map((r) => ({
+    side: r.side as Side, manager: addr(r.manager), wallet: addr(r.wallet), poolId: hex(r.poolId),
+    baseIn: big(r.baseIn), quoteIn: big(r.quoteIn), baseOut: big(r.baseOut), quoteOut: big(r.quoteOut),
+    feesRealised: big(r.feesRealised), dividendsClaimed: big(r.dividendsClaimed), redeemedQuote: big(r.redeemedQuote),
+    entries: num(r.entries), exits: num(r.exits), firstTime: secs(r.firstTime), lastTime: secs(r.lastTime),
+  }));
+}
+
+// ─── swap_flow ───────────────────────────────────────────────────────────────
+
+/** A swap's volume and fee in quote, the app's definitions (C: the quote leg and the event's fee; F: see VIEWS.md). F rows carry the traded legs and their L_j = w_j·L. */
+export interface SwapFlowRow {
+  side: Side;
+  manager: Address;
+  poolId: Hex;
+  txHash: Hex;
+  logIndex: number;
+  blockNumber: bigint;
+  blockTimestamp: number;
+  volumeQuote: bigint;
+  feeQuote: bigint;
+  tokenIn: Address | null;
+  tokenOut: Address | null;
+  reserveIn: bigint | null;
+  reserveOut: bigint | null;
+  lIn: bigint | null;
+  lOut: bigint | null;
+}
+export async function swapFlows(url: string, q: ViewQuery = {}): Promise<SwapFlowRow[]> {
+  const rows = await viewRows(url, "allSwapFlows", "SwapFlow", "side manager poolId txHash logIndex blockNumber blockTimestamp volumeQuote feeQuote tokenIn tokenOut reserveIn reserveOut lIn lOut", q);
+  return rows.map((r) => ({
+    side: r.side as Side, manager: addr(r.manager), poolId: hex(r.poolId), txHash: hex(r.txHash), logIndex: num(r.logIndex),
+    blockNumber: big(r.blockNumber), blockTimestamp: secs(r.blockTimestamp), volumeQuote: big(r.volumeQuote), feeQuote: big(r.feeQuote),
+    tokenIn: addrOr(r.tokenIn), tokenOut: addrOr(r.tokenOut), reserveIn: bigOr(r.reserveIn), reserveOut: bigOr(r.reserveOut), lIn: bigOr(r.lIn), lOut: bigOr(r.lOut),
+  }));
+}
+
+// ─── price_tick, candles ─────────────────────────────────────────────────────
+
+/** A price point per (pool, base) after a swap: C e^newX, F the traded leg's mark L_j / R_j. Quote wei per base wei. */
+export interface PriceTickRow {
+  side: Side;
+  poolId: Hex;
+  base: Address;
+  blockNumber: bigint;
+  blockTimestamp: number;
+  logIndex: number;
+  priceRaw: number;
+  volumeQuote: bigint;
+  feeQuote: bigint;
+}
+export async function priceTicks(url: string, q: ViewQuery = {}): Promise<PriceTickRow[]> {
+  const rows = await viewRows(url, "allPriceTicks", "PriceTick", "side poolId base blockNumber blockTimestamp logIndex priceRaw volumeQuote feeQuote", q);
+  return rows.map((r) => ({
+    side: r.side as Side, poolId: hex(r.poolId), base: addr(r.base), blockNumber: big(r.blockNumber), blockTimestamp: secs(r.blockTimestamp),
+    logIndex: num(r.logIndex), priceRaw: num(r.priceRaw), volumeQuote: big(r.volumeQuote), feeQuote: big(r.feeQuote),
+  }));
+}
+
+/** OHLC per (pool, base, UTC bucket). A base → base F swap counts in both legs' candles; pool totals come from {@link poolSummaries}. */
+export interface CandleRow {
+  side: Side;
+  poolId: Hex;
+  base: Address;
+  /** Bucket start, unix seconds. */
+  bucket: number;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volumeQuote: bigint;
+  feeQuote: bigint;
+  swaps: number;
+}
+export type CandleInterval = "minute" | "hour" | "day";
+const CANDLE: Record<CandleInterval, [string, string]> = { minute: ["allCandleMinutes", "CandleMinute"], hour: ["allCandleHours", "CandleHour"], day: ["allCandleDays", "CandleDay"] };
+export async function candles(url: string, interval: CandleInterval, q: ViewQuery = {}): Promise<CandleRow[]> {
+  const [field, type] = CANDLE[interval];
+  const rows = await viewRows(url, field, type, "side poolId base bucket open high low close volumeQuote feeQuote swaps", q);
+  return rows.map((r) => ({
+    side: r.side as Side, poolId: hex(r.poolId), base: addr(r.base), bucket: secs(r.bucket), open: num(r.open), high: num(r.high), low: num(r.low), close: num(r.close),
+    volumeQuote: big(r.volumeQuote), feeQuote: big(r.feeQuote), swaps: num(r.swaps),
+  }));
+}
+
+// ─── pool_tvl_hour ───────────────────────────────────────────────────────────
+
+/** The hour's last snapshot per pool (forward-fill hours with none). `liquidity` is C's active L or F's L. */
+export interface PoolTvlHourRow {
+  side: Side;
+  poolId: Hex;
+  bucket: number;
+  blockNumber: bigint;
+  tvlQuote: bigint | null;
+  liquidity: bigint | null;
+  /** C only. */
+  priceRaw: number | null;
+  feeGrowth: bigint | null;
+  /** F only. */
+  shareValue: bigint | null;
+  gen: number | null;
+}
+export async function poolTvlHours(url: string, q: ViewQuery = {}): Promise<PoolTvlHourRow[]> {
+  const rows = await viewRows(url, "allPoolTvlHours", "PoolTvlHour", "side poolId bucket blockNumber tvlQuote liquidity priceRaw feeGrowth shareValue gen", q);
+  return rows.map((r) => ({
+    side: r.side as Side, poolId: hex(r.poolId), bucket: secs(r.bucket), blockNumber: big(r.blockNumber), tvlQuote: bigOr(r.tvlQuote),
+    liquidity: bigOr(r.liquidity), priceRaw: numOr(r.priceRaw), feeGrowth: bigOr(r.feeGrowth), shareValue: bigOr(r.shareValue), gen: intOr(r.gen),
+  }));
+}
+
+// ─── pool_summary ────────────────────────────────────────────────────────────
+
+/**
+ * A pool's trailing 24 h / 7 d figures and its latest state. APY, as the app shows it: the window's
+ * swap fees over the pool's current L, annualised over the window measured (clipped to the pool's
+ * birth) — `fees / L × 31 536 000 / seconds`; the same formula as {@link swapFeeApy}.
+ */
+export interface PoolSummaryRow {
+  side: Side;
+  poolId: Hex;
+  kind: string;
+  quote: Address;
+  bases: Address[];
+  swapFee: bigint;
+  birthTime: number;
+  volume24h: bigint;
+  fees24h: bigint;
+  swaps24h: number;
+  volume7d: bigint;
+  fees7d: bigint;
+  volumeAll: bigint;
+  feesAll: bigint;
+  lastSwap: number | null;
+  tvlQuote: bigint | null;
+  liquidity: bigint | null;
+  priceRaw: number | null;
+  shareValue: bigint | null;
+  gen: number | null;
+  stateBlock: bigint | null;
+  seconds24h: number;
+  seconds7d: number;
+  apy24h: number | null;
+  apy7d: number | null;
+}
+export async function poolSummaries(url: string, q: ViewQuery = {}): Promise<PoolSummaryRow[]> {
+  const rows = await viewRows(
+    url, "allPoolSummaries", "PoolSummary",
+    "side poolId kind quote bases swapFee birthTime volume24H fees24H swaps24H volume7D fees7D volumeAll feesAll lastSwap tvlQuote liquidity priceRaw shareValue gen stateBlock seconds24H seconds7D apy24H apy7D",
+    q,
+  );
+  return rows.map((r) => ({
+    side: r.side as Side, poolId: hex(r.poolId), kind: String(r.kind), quote: addr(r.quote), bases: addrs(r.bases), swapFee: big(r.swapFee), birthTime: secs(r.birthTime),
+    volume24h: big(r.volume24H), fees24h: big(r.fees24H), swaps24h: num(r.swaps24H), volume7d: big(r.volume7D), fees7d: big(r.fees7D),
+    volumeAll: big(r.volumeAll), feesAll: big(r.feesAll), lastSwap: secsOr(r.lastSwap), tvlQuote: bigOr(r.tvlQuote), liquidity: bigOr(r.liquidity),
+    priceRaw: numOr(r.priceRaw), shareValue: bigOr(r.shareValue), gen: intOr(r.gen), stateBlock: bigOr(r.stateBlock),
+    seconds24h: num(r.seconds24H), seconds7d: num(r.seconds7D), apy24h: numOr(r.apy24H), apy7d: numOr(r.apy7D),
+  }));
+}
+
+// ─── generation_step, pad_status ─────────────────────────────────────────────
+
+/** A `regenerate` step: the pot and its split (payee, the protocol's cut, the burn, the rest deepening the bid); a pad's `rung` from `Graduated`. */
+export interface GenerationStepRow {
+  kind: string | null;
+  poolId: Hex;
+  /** The pool's generation after this step. */
+  genAfter: number;
+  pot: bigint;
+  payee: Address;
+  toPayee: bigint;
+  cut: bigint;
+  burnt: bigint;
+  deepened: bigint;
+  rung: number | null;
+  txHash: Hex;
+  blockNumber: bigint;
+  blockTimestamp: number;
+}
+export async function generationSteps(url: string, q: ViewQuery = {}): Promise<GenerationStepRow[]> {
+  const rows = await viewRows(url, "allGenerationSteps", "GenerationStep", "kind poolId genAfter pot payee toPayee cut burnt deepened rung txHash blockNumber blockTimestamp", q);
+  return rows.map((r) => ({
+    kind: r.kind == null ? null : String(r.kind), poolId: hex(r.poolId), genAfter: num(r.genAfter), pot: big(r.pot), payee: addr(r.payee),
+    toPayee: big(r.toPayee), cut: big(r.cut), burnt: big(r.burnt), deepened: big(r.deepened), rung: intOr(r.rung),
+    txHash: hex(r.txHash), blockNumber: big(r.blockNumber), blockTimestamp: secs(r.blockTimestamp),
+  }));
+}
+
+/** Every pad and POL now: the latest snapshot's state, the next graduation's threshold (pads) and the pot's progress to it, and the steps so far. */
+export interface PadStatusRow {
+  kind: string;
+  poolId: Hex;
+  quote: Address;
+  bases: Address[];
+  creator: Address | null;
+  birthTime: number;
+  gen: number | null;
+  pot: bigint | null;
+  unharvested: bigint | null;
+  l: bigint | null;
+  q: bigint | null;
+  tvlQuote: bigint | null;
+  shareValue: bigint | null;
+  threshold: bigint | null;
+  /** pot / threshold, a fraction; null without a threshold. */
+  progress: number | null;
+  stateBlock: bigint | null;
+  stateTime: number | null;
+  steps: number;
+  burntTotal: bigint;
+  cutTotal: bigint;
+  paidTotal: bigint;
+  deepenedTotal: bigint;
+  lastStep: number | null;
+}
+export async function padStatuses(url: string, q: ViewQuery = {}): Promise<PadStatusRow[]> {
+  const rows = await viewRows(
+    url, "allPadStatuses", "PadStatus",
+    "kind poolId quote bases creator birthTime gen pot unharvested l q tvlQuote shareValue threshold progress stateBlock stateTime steps burntTotal cutTotal paidTotal deepenedTotal lastStep",
+    q,
+  );
+  return rows.map((r) => ({
+    kind: String(r.kind), poolId: hex(r.poolId), quote: addr(r.quote), bases: addrs(r.bases), creator: addrOr(r.creator), birthTime: secs(r.birthTime),
+    gen: intOr(r.gen), pot: bigOr(r.pot), unharvested: bigOr(r.unharvested), l: bigOr(r.l), q: bigOr(r.q), tvlQuote: bigOr(r.tvlQuote),
+    shareValue: bigOr(r.shareValue), threshold: bigOr(r.threshold), progress: numOr(r.progress), stateBlock: bigOr(r.stateBlock), stateTime: secsOr(r.stateTime),
+    steps: num(r.steps), burntTotal: big(r.burntTotal), cutTotal: big(r.cutTotal), paidTotal: big(r.paidTotal), deepenedTotal: big(r.deepenedTotal), lastStep: secsOr(r.lastStep),
+  }));
+}
+
+// ─── protocol_revenue_day ────────────────────────────────────────────────────
+
+/**
+ * Protocol revenue per UTC day, side, source and token. Sources: F `mint_fee` (shares minted to the
+ * collector, valued at the share value) and `pot_cut`; C `accrued` (the swap-fee tax and the mint fee
+ * together, from the snapshots) and `collected` — basis `collected`, cash moved, not revenue on top
+ * of `accrued`.
+ */
+export interface ProtocolRevenueDayRow {
+  day: number;
+  side: Side;
+  source: string;
+  basis: "earned" | "collected";
+  token: Address;
+  amount: bigint;
+  amountQuote: bigint;
+  events: number;
+}
+export async function protocolRevenueDays(url: string, q: ViewQuery = {}): Promise<ProtocolRevenueDayRow[]> {
+  const rows = await viewRows(url, "allProtocolRevenueDays", "ProtocolRevenueDay", "day side source basis token amount amountQuote events", q);
+  return rows.map((r) => ({
+    day: secs(r.day), side: r.side as Side, source: String(r.source), basis: r.basis as "earned" | "collected", token: addr(r.token),
+    amount: big(r.amount), amountQuote: big(r.amountQuote), events: num(r.events),
+  }));
+}