@logswap/sdk 0.5.60 → 0.5.62

package/dist/history.d.ts

@@ -0,0 +1,61 @@
+/**
+ * history.ts — event history from the indexer, shaped like viem's `getLogs`, with the chain as the
+ * fallback.
+ *
+ * Every history read used to be a node `getLogs` from a pool's birth (or block 0) to the head: a
+ * full re-download on every page load, seconds each against a distant node, and silently partial
+ * once the node pruned its history. rindexer holds the same events with their block timestamps, so
+ * a window is a filter rather than a block search and a scan is one paged query.
+ *
+ * `getEventLogs` takes the ABI event exactly as `getLogs` does and derives the rest from it: the
+ * table (`all<Name>s`, or the manager-prefixed name where two contracts share an event name, as the
+ * ERC-6909 `Transfer` does), the columns (the inputs' names, camelCased as postgraphile does), and
+ * the decoding (the inputs' types — numbers as bigint, addresses checksummed, arrays from JSON).
+ * With no indexer URL, or when the query fails, it asks the node and says so in `source`.
+ */
+import { type AbiEvent, type Address, type Hex } from "viem";
+import type { LogswapClient } from "./client.js";
+/** One event, as `getLogs` returns it plus its block's timestamp (unix seconds). */
+export interface HistoryLog<A = Record<string, unknown>> {
+    address: Address;
+    args: A;
+    blockNumber: bigint;
+    /** Unix seconds. Always set from the indexer; set on the chain path only when a window asked for it. */
+    blockTimestamp?: number;
+    transactionHash: Hex;
+    logIndex: number;
+}
+export interface EventLogsQuery {
+    /** The rindexer GraphQL endpoint; absent means the chain. */
+    indexer?: string;
+    address: Address;
+    event: AbiEvent;
+    /** Indexed arguments to match, as `getLogs` takes them; an array matches any of its values. */
+    args?: Record<string, unknown>;
+    fromBlock?: bigint;
+    toBlock?: bigint;
+    /** Unix seconds: only events at or after this time. On the chain path it becomes a block search. */
+    since?: number;
+    /**
+     * Only the newest `latest` events (still returned oldest first) — a pool's tape, not its history.
+     * On the chain path the node is asked for the last {@link LATEST_SCAN_BLOCKS} blocks only.
+     */
+    latest?: number;
+    /** Only events from these transactions — e.g. the `RouterCall`s behind a page of routed swaps. */
+    transactionHashes?: Hex[];
+    signal?: AbortSignal;
+}
+/**
+ * The events, oldest first, and where they came from. `"indexer"` rows lag the head by the
+ * indexer's own lag — a few blocks at most on the devnet (logswap-health checks it).
+ */
+export declare function getEventLogs<A = Record<string, unknown>>(c: LogswapClient, q: EventLogsQuery): Promise<{
+    logs: HistoryLog<A>[];
+    source: "indexer" | "chain";
+}>;
+export declare function tableFor(c: LogswapClient, address: Address, event: string): {
+    field: string;
+    type: string;
+};
+/** How far back the chain path looks for a `latest` tape: a tape is recent by definition. */
+export declare const LATEST_SCAN_BLOCKS = 5000n;

package/dist/history.js

@@ -0,0 +1,166 @@
+/**
+ * history.ts — event history from the indexer, shaped like viem's `getLogs`, with the chain as the
+ * fallback.
+ *
+ * Every history read used to be a node `getLogs` from a pool's birth (or block 0) to the head: a
+ * full re-download on every page load, seconds each against a distant node, and silently partial
+ * once the node pruned its history. rindexer holds the same events with their block timestamps, so
+ * a window is a filter rather than a block search and a scan is one paged query.
+ *
+ * `getEventLogs` takes the ABI event exactly as `getLogs` does and derives the rest from it: the
+ * table (`all<Name>s`, or the manager-prefixed name where two contracts share an event name, as the
+ * ERC-6909 `Transfer` does), the columns (the inputs' names, camelCased as postgraphile does), and
+ * the decoding (the inputs' types — numbers as bigint, addresses checksummed, arrays from JSON).
+ * With no indexer URL, or when the query fails, it asks the node and says so in `source`.
+ */
+import { getAddress } from "viem";
+import { bytea, gql } from "./indexer.js";
+import { blockAtOrAfter } from "./fees.js";
+/**
+ * The events, oldest first, and where they came from. `"indexer"` rows lag the head by the
+ * indexer's own lag — a few blocks at most on the devnet (logswap-health checks it).
+ */
+export async function getEventLogs(c, q) {
+    if (q.indexer) {
+        try {
+            return { logs: await fromIndexer(c, q), source: "indexer" };
+        }
+        catch {
+            /* the indexer is a cache: when it cannot answer, the node can */
+        }
+    }
+    return { logs: await fromChain(c, q), source: "chain" };
+}
+// ─── the indexer path ────────────────────────────────────────────────────────
+/** What the rindexer deployment calls each manager — the prefix of a table two contracts share. */
+function contractName(c, address) {
+    const a = address.toLowerCase();
+    if (a === c.addresses.cPoolManager.toLowerCase())
+        return "LogswapManager";
+    if (c.addresses.fPoolManager && a === c.addresses.fPoolManager.toLowerCase())
+        return "FPoolManager";
+    if (a === c.addresses.router.toLowerCase())
+        return "LogswapRouter";
+    return null;
+}
+/** Events whose name two indexed contracts share: postgraphile prefixes their tables. */
+const SHARED = new Set(["Transfer"]);
+const plural = (n) => (/(s|x|ch|sh)$/.test(n) ? `${n}es` : `${n}s`);
+/** A column's GraphQL name: postgraphile camelCases the snake_case rindexer writes (`F` → `f`). */
+const column = (name) => name[0].toLowerCase() + name.slice(1);
+export function tableFor(c, address, event) {
+    const prefix = SHARED.has(event) ? contractName(c, address) : "";
+    if (prefix === null)
+        throw new Error(`history: no indexed contract at ${address}`);
+    const type = `${prefix}${event}`;
+    return { field: `all${plural(type)}`, type };
+}
+function decode(type, v) {
+    if (v === null || v === undefined)
+        return v;
+    if (type.endsWith("[]"))
+        return v.map((x) => decode(type.slice(0, -2), x));
+    if (type.startsWith("uint") || type.startsWith("int"))
+        return BigInt(v);
+    if (type === "address")
+        return getAddress(v);
+    return v; // bool, bytes32 (hex string), string
+}
+const PAGE = 1000;
+const MAX_PAGES = 200;
+async function fromIndexer(c, q) {
+    const { field, type } = tableFor(c, q.address, q.event.name);
+    const inputs = q.event.inputs;
+    const condition = {};
+    const filter = {};
+    for (const [k, v] of Object.entries(q.args ?? {})) {
+        const input = inputs.find((i) => i.name === k);
+        if (!input || v === undefined || v === null)
+            continue;
+        const enc = (x) => (input.type === "bytes32" ? bytea(x) : typeof x === "string" ? x.toLowerCase() : String(x));
+        if (Array.isArray(v)) {
+            // postgraphile's filter cannot match a bytea column; an OR over one leaves this to the chain
+            if (input.type === "bytes32")
+                throw new Error("history: OR over a bytes32 argument");
+            filter[column(k)] = { in: v.map(enc) };
+        }
+        else {
+            condition[column(k)] = enc(v);
+        }
+    }
+    const range = {};
+    if (q.fromBlock !== undefined)
+        range.greaterThanOrEqualTo = q.fromBlock.toString();
+    if (q.toBlock !== undefined)
+        range.lessThanOrEqualTo = q.toBlock.toString();
+    if (Object.keys(range).length)
+        filter.blockNumber = range;
+    if (q.since !== undefined)
+        filter.blockTimestamp = { greaterThanOrEqualTo: new Date(q.since * 1000).toISOString() };
+    if (q.transactionHashes)
+        filter.txHash = { in: q.transactionHashes.map((h) => h.toLowerCase()) };
+    // a tape is one page from the head, newest first; history is every page from the start
+    const pageSize = q.latest ?? PAGE;
+    const order = q.latest !== undefined ? "[BLOCK_NUMBER_DESC, LOG_INDEX_DESC]" : "PRIMARY_KEY_ASC";
+    const selection = [...inputs.map((i) => column(i.name)), "contractAddress", "blockNumber", "blockTimestamp", "txHash", "logIndex"].join(" ");
+    // postgraphile refuses a null or an empty filter, so each argument appears only when it has content
+    const hasCondition = Object.keys(condition).length > 0;
+    const hasFilter = Object.keys(filter).length > 0;
+    const decl = `$after: Cursor${hasCondition ? `, $condition: ${type}Condition` : ""}${hasFilter ? `, $filter: ${type}Filter` : ""}`;
+    const argsOf = `first: ${pageSize}, after: $after, orderBy: ${order}${hasCondition ? ", condition: $condition" : ""}${hasFilter ? ", filter: $filter" : ""}`;
+    const query = `query History(${decl}) {
+    ${field}(${argsOf}) {
+      pageInfo { hasNextPage endCursor } nodes { ${selection} }
+    }
+  }`;
+    const rows = [];
+    let after = null;
+    for (let i = 0;; i++) {
+        if (i === MAX_PAGES)
+            throw new Error(`history: ${field} has more than ${PAGE * MAX_PAGES} rows`);
+        const d = await gql(q.indexer, query, { after, ...(hasCondition ? { condition } : {}), ...(hasFilter ? { filter } : {}) }, q.signal);
+        const page = d[field];
+        rows.push(...page.nodes);
+        if (q.latest !== undefined || !page.pageInfo.hasNextPage || !page.pageInfo.endCursor)
+            break;
+        after = page.pageInfo.endCursor;
+    }
+    // a table can hold a previous deployment's rows (an indexer not yet reset): keep this contract's
+    const want = q.address.toLowerCase();
+    return rows
+        .filter((r) => String(r.contractAddress).toLowerCase() === want)
+        .map((r) => ({
+        address: q.address,
+        args: Object.fromEntries(inputs.map((i) => [i.name, decode(i.type, r[column(i.name)])])),
+        blockNumber: BigInt(r.blockNumber),
+        blockTimestamp: Math.floor(Date.parse(r.blockTimestamp) / 1000),
+        transactionHash: r.txHash,
+        logIndex: Number(r.logIndex),
+    }))
+        .sort((a, b) => (a.blockNumber === b.blockNumber ? a.logIndex - b.logIndex : a.blockNumber < b.blockNumber ? -1 : 1));
+}
+// ─── the chain path ──────────────────────────────────────────────────────────
+/** How far back the chain path looks for a `latest` tape: a tape is recent by definition. */
+export const LATEST_SCAN_BLOCKS = 5000n;
+async function fromChain(c, q) {
+    let fromBlock = q.fromBlock ?? 0n;
+    const toBlock = q.toBlock ?? (await c.public.getBlockNumber());
+    if (q.since !== undefined)
+        fromBlock = await blockAtOrAfter(c, BigInt(q.since), fromBlock, toBlock);
+    if (q.latest !== undefined && toBlock - fromBlock > LATEST_SCAN_BLOCKS)
+        fromBlock = toBlock - LATEST_SCAN_BLOCKS;
+    let logs = (await c.public.getLogs({ address: q.address, event: q.event, args: q.args, fromBlock, toBlock }));
+    if (q.transactionHashes) {
+        const want = new Set(q.transactionHashes.map((h) => h.toLowerCase()));
+        logs = logs.filter((l) => want.has(l.transactionHash.toLowerCase()));
+    }
+    if (q.latest !== undefined)
+        logs = logs.slice(-q.latest);
+    return logs.map((l) => ({
+        address: q.address,
+        args: l.args,
+        blockNumber: l.blockNumber,
+        transactionHash: l.transactionHash,
+        logIndex: l.logIndex,
+    }));
+}

package/dist/index.d.ts

@@ -20,5 +20,6 @@ export * from "./indexer.js";
 export * from "./tokencache.js";
 export * from "./fpool.js";
 export * from "./fees.js";
+export * from "./history.js";
 export { cPoolManagerAbi, fPoolManagerAbi, logswapLensAbi, logswapRouterAbi, padPolicyAbi, polPolicyAbi, policyRegistryAbi, privatePolicyAbi, publicPolicyAbi } from "./generated.js";
 export * from "./admin.js";

package/dist/index.js

@@ -20,5 +20,6 @@ export * from "./indexer.js";
 export * from "./tokencache.js";
 export * from "./fpool.js";
 export * from "./fees.js";
+export * from "./history.js";
 export { cPoolManagerAbi, fPoolManagerAbi, logswapLensAbi, logswapRouterAbi, padPolicyAbi, polPolicyAbi, policyRegistryAbi, privatePolicyAbi, publicPolicyAbi } from "./generated.js";
 export * from "./admin.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logswap/sdk",
-  "version": "0.5.60",
+  "version": "0.5.62",
   "description": "TypeScript SDK for Logswap, the liquidity primitive introducing the logarithmic invariant — typed wrappers over the CPoolManager / FPoolManager / Router / Lens surface.",
   "license": "GPL-2.0-or-later",
   "type": "module",

package/src/history.ts

@@ -0,0 +1,205 @@
+/**
+ * history.ts — event history from the indexer, shaped like viem's `getLogs`, with the chain as the
+ * fallback.
+ *
+ * Every history read used to be a node `getLogs` from a pool's birth (or block 0) to the head: a
+ * full re-download on every page load, seconds each against a distant node, and silently partial
+ * once the node pruned its history. rindexer holds the same events with their block timestamps, so
+ * a window is a filter rather than a block search and a scan is one paged query.
+ *
+ * `getEventLogs` takes the ABI event exactly as `getLogs` does and derives the rest from it: the
+ * table (`all<Name>s`, or the manager-prefixed name where two contracts share an event name, as the
+ * ERC-6909 `Transfer` does), the columns (the inputs' names, camelCased as postgraphile does), and
+ * the decoding (the inputs' types — numbers as bigint, addresses checksummed, arrays from JSON).
+ * With no indexer URL, or when the query fails, it asks the node and says so in `source`.
+ */
+import { getAddress, type AbiEvent, type Address, type Hex } from "viem";
+import type { LogswapClient } from "./client.js";
+import { bytea, gql } from "./indexer.js";
+import { blockAtOrAfter } from "./fees.js";
+
+/** One event, as `getLogs` returns it plus its block's timestamp (unix seconds). */
+export interface HistoryLog<A = Record<string, unknown>> {
+  address: Address;
+  args: A;
+  blockNumber: bigint;
+  /** Unix seconds. Always set from the indexer; set on the chain path only when a window asked for it. */
+  blockTimestamp?: number;
+  transactionHash: Hex;
+  logIndex: number;
+}
+
+export interface EventLogsQuery {
+  /** The rindexer GraphQL endpoint; absent means the chain. */
+  indexer?: string;
+  address: Address;
+  event: AbiEvent;
+  /** Indexed arguments to match, as `getLogs` takes them; an array matches any of its values. */
+  args?: Record<string, unknown>;
+  fromBlock?: bigint;
+  toBlock?: bigint;
+  /** Unix seconds: only events at or after this time. On the chain path it becomes a block search. */
+  since?: number;
+  /**
+   * Only the newest `latest` events (still returned oldest first) — a pool's tape, not its history.
+   * On the chain path the node is asked for the last {@link LATEST_SCAN_BLOCKS} blocks only.
+   */
+  latest?: number;
+  /** Only events from these transactions — e.g. the `RouterCall`s behind a page of routed swaps. */
+  transactionHashes?: Hex[];
+  signal?: AbortSignal;
+}
+
+/**
+ * The events, oldest first, and where they came from. `"indexer"` rows lag the head by the
+ * indexer's own lag — a few blocks at most on the devnet (logswap-health checks it).
+ */
+export async function getEventLogs<A = Record<string, unknown>>(
+  c: LogswapClient,
+  q: EventLogsQuery,
+): Promise<{ logs: HistoryLog<A>[]; source: "indexer" | "chain" }> {
+  if (q.indexer) {
+    try {
+      return { logs: await fromIndexer<A>(c, q), source: "indexer" };
+    } catch {
+      /* the indexer is a cache: when it cannot answer, the node can */
+    }
+  }
+  return { logs: await fromChain<A>(c, q), source: "chain" };
+}
+
+// ─── the indexer path ────────────────────────────────────────────────────────
+
+/** What the rindexer deployment calls each manager — the prefix of a table two contracts share. */
+function contractName(c: LogswapClient, address: Address): string | null {
+  const a = address.toLowerCase();
+  if (a === c.addresses.cPoolManager.toLowerCase()) return "LogswapManager";
+  if (c.addresses.fPoolManager && a === c.addresses.fPoolManager.toLowerCase()) return "FPoolManager";
+  if (a === c.addresses.router.toLowerCase()) return "LogswapRouter";
+  return null;
+}
+
+/** Events whose name two indexed contracts share: postgraphile prefixes their tables. */
+const SHARED = new Set(["Transfer"]);
+
+const plural = (n: string) => (/(s|x|ch|sh)$/.test(n) ? `${n}es` : `${n}s`);
+/** A column's GraphQL name: postgraphile camelCases the snake_case rindexer writes (`F` → `f`). */
+const column = (name: string) => name[0]!.toLowerCase() + name.slice(1);
+
+export function tableFor(c: LogswapClient, address: Address, event: string): { field: string; type: string } {
+  const prefix = SHARED.has(event) ? contractName(c, address) : "";
+  if (prefix === null) throw new Error(`history: no indexed contract at ${address}`);
+  const type = `${prefix}${event}`;
+  return { field: `all${plural(type)}`, type };
+}
+
+function decode(type: string, v: unknown): unknown {
+  if (v === null || v === undefined) return v;
+  if (type.endsWith("[]")) return (v as unknown[]).map((x) => decode(type.slice(0, -2), x));
+  if (type.startsWith("uint") || type.startsWith("int")) return BigInt(v as string);
+  if (type === "address") return getAddress(v as string);
+  return v; // bool, bytes32 (hex string), string
+}
+
+const PAGE = 1000;
+const MAX_PAGES = 200;
+
+async function fromIndexer<A>(c: LogswapClient, q: EventLogsQuery): Promise<HistoryLog<A>[]> {
+  const { field, type } = tableFor(c, q.address, q.event.name);
+  const inputs = q.event.inputs;
+  const condition: Record<string, unknown> = {};
+  const filter: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(q.args ?? {})) {
+    const input = inputs.find((i) => i.name === k);
+    if (!input || v === undefined || v === null) continue;
+    const enc = (x: unknown) => (input.type === "bytes32" ? bytea(x as Hex) : typeof x === "string" ? x.toLowerCase() : String(x));
+    if (Array.isArray(v)) {
+      // postgraphile's filter cannot match a bytea column; an OR over one leaves this to the chain
+      if (input.type === "bytes32") throw new Error("history: OR over a bytes32 argument");
+      filter[column(k)] = { in: v.map(enc) };
+    } else {
+      condition[column(k)] = enc(v);
+    }
+  }
+  const range: Record<string, string> = {};
+  if (q.fromBlock !== undefined) range.greaterThanOrEqualTo = q.fromBlock.toString();
+  if (q.toBlock !== undefined) range.lessThanOrEqualTo = q.toBlock.toString();
+  if (Object.keys(range).length) filter.blockNumber = range;
+  if (q.since !== undefined) filter.blockTimestamp = { greaterThanOrEqualTo: new Date(q.since * 1000).toISOString() };
+  if (q.transactionHashes) filter.txHash = { in: q.transactionHashes.map((h) => h.toLowerCase()) };
+  // a tape is one page from the head, newest first; history is every page from the start
+  const pageSize = q.latest ?? PAGE;
+  const order = q.latest !== undefined ? "[BLOCK_NUMBER_DESC, LOG_INDEX_DESC]" : "PRIMARY_KEY_ASC";
+
+  const selection = [...inputs.map((i) => column(i.name!)), "contractAddress", "blockNumber", "blockTimestamp", "txHash", "logIndex"].join(" ");
+  // postgraphile refuses a null or an empty filter, so each argument appears only when it has content
+  const hasCondition = Object.keys(condition).length > 0;
+  const hasFilter = Object.keys(filter).length > 0;
+  const decl = `$after: Cursor${hasCondition ? `, $condition: ${type}Condition` : ""}${hasFilter ? `, $filter: ${type}Filter` : ""}`;
+  const argsOf = `first: ${pageSize}, after: $after, orderBy: ${order}${hasCondition ? ", condition: $condition" : ""}${hasFilter ? ", filter: $filter" : ""}`;
+  const query = `query History(${decl}) {
+    ${field}(${argsOf}) {
+      pageInfo { hasNextPage endCursor } nodes { ${selection} }
+    }
+  }`;
+  type Row = Record<string, unknown>;
+  type Conn = { pageInfo: { hasNextPage: boolean; endCursor: string | null }; nodes: Row[] };
+  const rows: Row[] = [];
+  let after: string | null = null;
+  for (let i = 0; ; i++) {
+    if (i === MAX_PAGES) throw new Error(`history: ${field} has more than ${PAGE * MAX_PAGES} rows`);
+    const d: Record<string, Conn> = await gql<Record<string, Conn>>(
+      q.indexer!,
+      query,
+      { after, ...(hasCondition ? { condition } : {}), ...(hasFilter ? { filter } : {}) },
+      q.signal,
+    );
+    const page: Conn = d[field]!;
+    rows.push(...page.nodes);
+    if (q.latest !== undefined || !page.pageInfo.hasNextPage || !page.pageInfo.endCursor) break;
+    after = page.pageInfo.endCursor;
+  }
+  // a table can hold a previous deployment's rows (an indexer not yet reset): keep this contract's
+  const want = q.address.toLowerCase();
+  return rows
+    .filter((r) => String(r.contractAddress).toLowerCase() === want)
+    .map((r) => ({
+      address: q.address,
+      args: Object.fromEntries(inputs.map((i) => [i.name!, decode(i.type, r[column(i.name!)])])) as A,
+      blockNumber: BigInt(r.blockNumber as string),
+      blockTimestamp: Math.floor(Date.parse(r.blockTimestamp as string) / 1000),
+      transactionHash: r.txHash as Hex,
+      logIndex: Number(r.logIndex),
+    }))
+    .sort((a, b) => (a.blockNumber === b.blockNumber ? a.logIndex - b.logIndex : a.blockNumber < b.blockNumber ? -1 : 1));
+}
+
+// ─── the chain path ──────────────────────────────────────────────────────────
+
+/** How far back the chain path looks for a `latest` tape: a tape is recent by definition. */
+export const LATEST_SCAN_BLOCKS = 5_000n;
+
+async function fromChain<A>(c: LogswapClient, q: EventLogsQuery): Promise<HistoryLog<A>[]> {
+  let fromBlock = q.fromBlock ?? 0n;
+  const toBlock = q.toBlock ?? (await c.public.getBlockNumber());
+  if (q.since !== undefined) fromBlock = await blockAtOrAfter(c, BigInt(q.since), fromBlock, toBlock);
+  if (q.latest !== undefined && toBlock - fromBlock > LATEST_SCAN_BLOCKS) fromBlock = toBlock - LATEST_SCAN_BLOCKS;
+  let logs = (await c.public.getLogs({ address: q.address, event: q.event, args: q.args, fromBlock, toBlock } as never)) as unknown as Array<{
+    args: A;
+    blockNumber: bigint;
+    transactionHash: Hex;
+    logIndex: number;
+  }>;
+  if (q.transactionHashes) {
+    const want = new Set(q.transactionHashes.map((h) => h.toLowerCase()));
+    logs = logs.filter((l) => want.has(l.transactionHash.toLowerCase()));
+  }
+  if (q.latest !== undefined) logs = logs.slice(-q.latest);
+  return logs.map((l) => ({
+    address: q.address,
+    args: l.args,
+    blockNumber: l.blockNumber,
+    transactionHash: l.transactionHash,
+    logIndex: l.logIndex,
+  }));
+}

package/src/index.ts

@@ -20,5 +20,6 @@ export * from "./indexer.js";
 export * from "./tokencache.js";
 export * from "./fpool.js";
 export * from "./fees.js";
+export * from "./history.js";
 export { cPoolManagerAbi, fPoolManagerAbi, logswapLensAbi, logswapRouterAbi, padPolicyAbi, polPolicyAbi, policyRegistryAbi, privatePolicyAbi, publicPolicyAbi } from "./generated.js";
 export * from "./admin.js";