@notuslabs/yail 0.1.0

package/dist/schema/ddl.d.ts

@@ -0,0 +1,9 @@
+import { type Table } from "./table.js";
+import type { MaterializedView } from "./view.js";
+import { qualify } from "../db/sql.js";
+export { qualify };
+export declare function tableDdl(table: Table<any>, database?: string): string;
+export declare function materializedViewDdl(view: MaterializedView, database?: string): string;
+/** One-off backfill of a materialized view's target from existing source data. */
+export declare function materializedViewPopulateSql(view: MaterializedView, database?: string): string;
+//# sourceMappingURL=ddl.d.ts.map

package/dist/schema/ddl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ddl.d.ts","sourceRoot":"","sources":["../../src/schema/ddl.ts"],"names":[],"mappings":"AACA,OAAO,EAAsB,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,OAAO,EAAa,MAAM,cAAc,CAAC;AAElD,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAoCrE;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAGrF;AAED,kFAAkF;AAClF,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,gBAAgB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7F"}

package/dist/schema/ddl.js

@@ -0,0 +1,58 @@
+import { columnTypeSql } from "./column.js";
+import { INDEX_META_COLUMNS } from "./table.js";
+import { qualify, renderSql } from "../db/sql.js";
+export { qualify };
+export function tableDdl(table, database) {
+    const cols = [];
+    for (const key of table.columnKeys) {
+        const col = table.columns[key];
+        let line = `\`${table.columnName(key)}\` ${columnTypeSql(col)}`;
+        if (col.hasDefault && col.defaultSql)
+            line += ` DEFAULT ${col.defaultSql}`;
+        if (col.codecSql)
+            line += ` CODEC(${col.codecSql})`;
+        cols.push(line);
+    }
+    const meta = table.options.indexMeta !== false;
+    if (meta) {
+        cols.push(`\`${INDEX_META_COLUMNS.chain}\` LowCardinality(String) DEFAULT ''`);
+        cols.push(`\`${INDEX_META_COLUMNS.block}\` UInt64 DEFAULT 0`);
+        cols.push(`\`${INDEX_META_COLUMNS.version}\` UInt64 DEFAULT 0`);
+    }
+    const engine = table.options.engine ?? "ReplacingMergeTree";
+    let engineArgs = table.options.engineArgs ?? [];
+    if ((engine === "ReplacingMergeTree" || engine === "ReplicatedReplacingMergeTree") && engineArgs.length === 0 && meta) {
+        engineArgs = [INDEX_META_COLUMNS.version];
+    }
+    const orderBy = table.options.orderBy.map((k) => `\`${table.columnName(k)}\``).join(", ");
+    const parts = [
+        `CREATE TABLE IF NOT EXISTS ${qualify(table.name, database)} (\n  ${cols.join(",\n  ")}\n)`,
+        `ENGINE = ${engine}(${engineArgs.join(", ")})`,
+    ];
+    if (table.options.partitionBy)
+        parts.push(`PARTITION BY ${table.options.partitionBy}`);
+    parts.push(`ORDER BY (${orderBy})`);
+    if (table.options.ttl)
+        parts.push(`TTL ${table.options.ttl}`);
+    if (table.options.settings && Object.keys(table.options.settings).length > 0) {
+        parts.push(`SETTINGS ${Object.entries(table.options.settings)
+            .map(([k, v]) => `${k} = ${settingValue(v)}`)
+            .join(", ")}`);
+    }
+    return parts.join("\n");
+}
+export function materializedViewDdl(view, database) {
+    const { text } = renderSql(view.query, { inline: true, database });
+    return `CREATE MATERIALIZED VIEW IF NOT EXISTS ${qualify(view.name, database)} TO ${qualify(view.to.name, database)} AS\n${text}`;
+}
+/** One-off backfill of a materialized view's target from existing source data. */
+export function materializedViewPopulateSql(view, database) {
+    const { text } = renderSql(view.query, { inline: true, database });
+    return `INSERT INTO ${qualify(view.to.name, database)}\n${text}`;
+}
+function settingValue(v) {
+    if (typeof v === "number")
+        return String(v);
+    return `'${v}'`;
+}
+//# sourceMappingURL=ddl.js.map

package/dist/schema/ddl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ddl.js","sourceRoot":"","sources":["../../src/schema/ddl.ts"],"names":[],"mappings":"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"}

package/dist/schema/index.d.ts

@@ -0,0 +1,8 @@
+export { t, columnTypeSql } from "./column.js";
+export type { Column, ColumnKind } from "./column.js";
+export { table, isTable, snakeCase, INDEX_META_COLUMNS } from "./table.js";
+export type { Table, TableOptions, TableEngine, InsertRow, InferRow, Columns } from "./table.js";
+export { materializedView, isMaterializedView } from "./view.js";
+export type { MaterializedView } from "./view.js";
+export { tableDdl, materializedViewDdl, materializedViewPopulateSql } from "./ddl.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/schema/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC3E,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACjG,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACjE,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC"}

package/dist/schema/index.js

@@ -0,0 +1,5 @@
+export { t, columnTypeSql } from "./column.js";
+export { table, isTable, snakeCase, INDEX_META_COLUMNS } from "./table.js";
+export { materializedView, isMaterializedView } from "./view.js";
+export { tableDdl, materializedViewDdl, materializedViewPopulateSql } from "./ddl.js";
+//# sourceMappingURL=index.js.map

package/dist/schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE3E,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC"}

package/dist/schema/table.d.ts

@@ -0,0 +1,69 @@
+import type { Column } from "./column.js";
+export type Columns = Record<string, Column<any, boolean, boolean>>;
+export type TableEngine = "MergeTree" | "ReplacingMergeTree" | "SummingMergeTree" | "AggregatingMergeTree" | "CollapsingMergeTree" | "ReplicatedMergeTree" | "ReplicatedReplacingMergeTree";
+export interface TableOptions<C extends Columns> {
+    /**
+     * Sorting key / primary key. Rows with the same key are deduplicated on
+     * ReplacingMergeTree (the default engine), which is what makes re-indexing
+     * idempotent. Choose the natural identity of a row (e.g. chain + tx + logIndex).
+     */
+    orderBy: ReadonlyArray<keyof C & string>;
+    /** Raw ClickHouse PARTITION BY expression, e.g. `toYYYYMM(block_time)`. */
+    partitionBy?: string;
+    /** Defaults to ReplacingMergeTree versioned by the internal `_yail_version` column. */
+    engine?: TableEngine;
+    /** Extra engine args (e.g. summed columns for SummingMergeTree). Not needed for Replacing. */
+    engineArgs?: string[];
+    /** Raw TTL expression. */
+    ttl?: string;
+    /** Extra SETTINGS for the table. */
+    settings?: Record<string, string | number>;
+    /**
+     * Entity scopes for targeted re-indexing. Keys are scope names (e.g. `wallet`,
+     * `pool`) and values are the column holding the entity id. `yail reindex
+     * --scope wallet=0xabc` deletes matching rows in every table declaring that scope.
+     */
+    scopes?: Record<string, keyof C & string>;
+    /**
+     * Whether to add the hidden bookkeeping columns `_yail_chain`, `_yail_block`,
+     * `_yail_version`. Required for range re-indexing and versioned dedup. Default true.
+     */
+    indexMeta?: boolean;
+    /** Optional column name overrides: TS key -> ClickHouse column name. Defaults to snake_case. */
+    columnNames?: Partial<Record<keyof C & string, string>>;
+}
+export interface Table<C extends Columns = Columns> {
+    readonly __brand: "yail.table";
+    readonly name: string;
+    readonly columns: C;
+    readonly options: TableOptions<C>;
+    /** TS key -> ClickHouse column name. */
+    readonly columnName: (key: keyof C & string) => string;
+    readonly columnKeys: ReadonlyArray<keyof C & string>;
+    toString(): string;
+}
+type OptionalKeys<C extends Columns> = {
+    [K in keyof C]: C[K]["isNullable"] extends true ? K : C[K]["hasDefault"] extends true ? K : never;
+}[keyof C];
+type RequiredKeys<C extends Columns> = Exclude<keyof C, OptionalKeys<C>>;
+type ColType<Col> = Col extends Column<infer T, infer N, boolean> ? (N extends true ? T | null : T) : never;
+/** Row type accepted by `db.insert(table).values(row)`. */
+export type InsertRow<T extends Table<any>> = T extends Table<infer C> ? {
+    [K in RequiredKeys<C>]: ColType<C[K]>;
+} & {
+    [K in OptionalKeys<C>]?: ColType<C[K]> | undefined;
+} : never;
+/** Row type returned by `db.rows(table, ...)`. */
+export type InferRow<T extends Table<any>> = T extends Table<infer C> ? {
+    [K in keyof C]: ColType<C[K]>;
+} : never;
+export declare const INDEX_META_COLUMNS: {
+    readonly chain: "_yail_chain";
+    readonly block: "_yail_block";
+    readonly version: "_yail_version";
+};
+export declare function snakeCase(s: string): string;
+export declare function table<C extends Columns>(name: string, columns: C, options: TableOptions<C>): Table<C>;
+export declare function isTable(v: unknown): v is Table;
+export {};
+//# sourceMappingURL=table.d.ts.map

package/dist/schema/table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/schema/table.ts"],"names":[],"mappings":"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"}

package/dist/schema/table.js

@@ -0,0 +1,35 @@
+export const INDEX_META_COLUMNS = {
+    chain: "_yail_chain",
+    block: "_yail_block",
+    version: "_yail_version",
+};
+export function snakeCase(s) {
+    return s.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/([A-Z])([A-Z][a-z])/g, "$1_$2").toLowerCase();
+}
+export function table(name, columns, options) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name))
+        throw new Error(`Invalid table name "${name}"`);
+    for (const key of options.orderBy) {
+        if (!(key in columns))
+            throw new Error(`Table "${name}": orderBy column "${key}" does not exist`);
+    }
+    for (const [scope, col] of Object.entries(options.scopes ?? {})) {
+        if (!(col in columns))
+            throw new Error(`Table "${name}": scope "${scope}" points to unknown column "${col}"`);
+    }
+    const overrides = options.columnNames ?? {};
+    const columnName = (key) => overrides[key] ?? snakeCase(key);
+    return {
+        __brand: "yail.table",
+        name,
+        columns,
+        options: { indexMeta: true, engine: "ReplacingMergeTree", ...options },
+        columnName,
+        columnKeys: Object.keys(columns),
+        toString: () => name,
+    };
+}
+export function isTable(v) {
+    return typeof v === "object" && v !== null && v.__brand === "yail.table";
+}
+//# sourceMappingURL=table.js.map

package/dist/schema/table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.js","sourceRoot":"","sources":["../../src/schema/table.ts"],"names":[],"mappings":"AAuEA,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,KAAK,EAAE,aAAa;IACpB,KAAK,EAAE,aAAa;IACpB,OAAO,EAAE,eAAe;CAChB,CAAC;AAEX,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,OAAO,CAAC,CAAC,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,sBAAsB,EAAE,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;AACzG,CAAC;AAED,MAAM,UAAU,KAAK,CAAoB,IAAY,EAAE,OAAU,EAAE,OAAwB;IACzF,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,IAAI,GAAG,CAAC,CAAC;IAC5F,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QAClC,IAAI,CAAC,CAAC,GAAG,IAAI,OAAO,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,UAAU,IAAI,sBAAsB,GAAG,kBAAkB,CAAC,CAAC;IACpG,CAAC;IACD,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;QAChE,IAAI,CAAC,CAAC,GAAG,IAAI,OAAO,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,UAAU,IAAI,aAAa,KAAK,+BAA+B,GAAG,GAAG,CAAC,CAAC;IAChH,CAAC;IACD,MAAM,SAAS,GAA8C,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC;IACvF,MAAM,UAAU,GAAG,CAAC,GAAqB,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC;IAC/E,OAAO;QACL,OAAO,EAAE,YAAY;QACrB,IAAI;QACJ,OAAO;QACP,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,oBAAoB,EAAE,GAAG,OAAO,EAAE;QACtE,UAAU;QACV,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAA4B;QAC3D,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI;KACrB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,CAAU;IAChC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAAW,CAAC,OAAO,KAAK,YAAY,CAAC;AACtF,CAAC"}

package/dist/schema/view.d.ts

@@ -0,0 +1,19 @@
+import type { Table } from "./table.js";
+import type { SqlFragment } from "../db/sql.js";
+export interface MaterializedView {
+    readonly __brand: "yail.materializedView";
+    readonly name: string;
+    /** Target table the view writes into (must be created, use `table()`). */
+    readonly to: Table<any>;
+    /** The SELECT that transforms inserts into rows of `to`. */
+    readonly query: SqlFragment;
+    /** Source table(s), used for `yail migrate --populate` ordering and docs. */
+    readonly from: ReadonlyArray<Table<any>>;
+}
+export declare function materializedView(name: string, def: {
+    to: Table<any>;
+    from: Table<any> | ReadonlyArray<Table<any>>;
+    query: SqlFragment;
+}): MaterializedView;
+export declare function isMaterializedView(v: unknown): v is MaterializedView;
+//# sourceMappingURL=view.d.ts.map

package/dist/schema/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../src/schema/view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;CAC1C;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE;IAAE,EAAE,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GACxF,gBAAgB,CASlB;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,gBAAgB,CAEpE"}

package/dist/schema/view.js

@@ -0,0 +1,16 @@
+import { toArray } from "../util.js";
+export function materializedView(name, def) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name))
+        throw new Error(`Invalid view name "${name}"`);
+    return {
+        __brand: "yail.materializedView",
+        name,
+        to: def.to,
+        query: def.query,
+        from: toArray(def.from),
+    };
+}
+export function isMaterializedView(v) {
+    return typeof v === "object" && v !== null && v.__brand === "yail.materializedView";
+}
+//# sourceMappingURL=view.js.map

package/dist/schema/view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../../src/schema/view.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAarC,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,GAAyF;IAEzF,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,IAAI,GAAG,CAAC,CAAC;IAC3F,OAAO;QACL,OAAO,EAAE,uBAAuB;QAChC,IAAI;QACJ,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,IAAI,EAAE,OAAO,CAAa,GAAG,CAAC,IAAI,CAAC;KACpC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,CAAU;IAC3C,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAAsB,CAAC,OAAO,KAAK,uBAAuB,CAAC;AAC5G,CAAC"}

package/dist/server/api.d.ts

@@ -0,0 +1,11 @@
+import { Hono } from "hono";
+import type { Indexer } from "../indexer/indexer.js";
+export declare function createApp(indexer: Indexer<any>): Hono;
+export declare function startServer(indexer: Indexer<any>, options: {
+    port: number;
+    hostname?: string;
+}): Promise<{
+    close(): Promise<void>;
+    port: number;
+}>;
+//# sourceMappingURL=api.d.ts.map

package/dist/server/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/server/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAKrD,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAqDrD;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC;IAAE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CASxJ"}

package/dist/server/api.js

@@ -0,0 +1,71 @@
+import { Hono } from "hono";
+import { serve } from "@hono/node-server";
+import { jobs as jobsTable } from "../db/internal.js";
+import { sql } from "../db/sql.js";
+import { bigintReplacer, toArray } from "../util.js";
+export function createApp(indexer) {
+    const app = new Hono();
+    app.get("/health", async (c) => {
+        const status = await indexer.status();
+        const failed = Object.values(status.chains).filter((ch) => ch.error);
+        return c.json({ ok: failed.length === 0, failed: failed.length }, statusCode(failed.length === 0));
+    });
+    app.get("/ready", async (c) => {
+        const status = await indexer.status();
+        const ready = Object.values(status.chains).every((ch) => ch.caughtUp && !ch.error);
+        return c.json({ ready, chains: Object.fromEntries(Object.entries(status.chains).map(([k, v]) => [k, { caughtUp: v.caughtUp, lagBlocks: v.lagBlocks }])) }, statusCode(ready));
+    });
+    app.get("/status", async (c) => c.json(await indexer.status()));
+    app.get("/addresses", (c) => {
+        const set = c.req.query("set");
+        const chain = c.req.query("chain");
+        const status = c.req.query("status");
+        return c.json(indexer.addresses.list({ set, chain, status }).map(serializable));
+    });
+    app.post("/addresses", async (c) => {
+        const body = await c.req.json();
+        if (!body.set || !body.address)
+            return c.json({ error: "set and address are required" }, 400);
+        const list = toArray(body.address).map((address) => ({ set: body.set, address, chain: body.chain, fromBlock: body.fromBlock, meta: body.meta }));
+        const rows = await indexer.addresses.register(list);
+        return c.json(rows.map(serializable), 201);
+    });
+    app.post("/reindex", async (c) => {
+        const body = await c.req.json();
+        try {
+            const rows = await indexer.reindex(body);
+            return c.json(rows.map(serializable), 202);
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.get("/jobs", async (c) => {
+        const rows = await indexer.db.rows(jobsTable, sql `ORDER BY created_at DESC LIMIT 200`);
+        return c.json(rows.map(serializable));
+    });
+    app.get("/_evlog/logs", (c) => {
+        const limit = Number(c.req.query("limit") ?? 100);
+        return c.json(indexer.observability.recentEvents(limit));
+    });
+    return app;
+}
+export async function startServer(indexer, options) {
+    const app = createApp(indexer);
+    const server = serve({ fetch: app.fetch, port: options.port, hostname: options.hostname ?? "0.0.0.0" });
+    const port = server.address()?.port ?? options.port;
+    indexer.observability.log.info("yail", `status API listening on http://${options.hostname ?? "0.0.0.0"}:${port} (/status, /health, /addresses, /reindex, /jobs)`);
+    return {
+        port,
+        close: () => new Promise((resolve) => server.close(() => resolve())),
+    };
+}
+function statusCode(ok) {
+    if (ok)
+        return 200;
+    return 503;
+}
+function serializable(v) {
+    return JSON.parse(JSON.stringify(v, bigintReplacer));
+}
+//# sourceMappingURL=api.js.map

package/dist/server/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/server/api.ts"],"names":[],"mappings":"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"}

package/dist/sources/cached.d.ts

@@ -0,0 +1,27 @@
+import type { Db } from "../db/client.js";
+import type { BitcoinSource, EvmSource, RangeQuery, Source } from "./types.js";
+export interface CachedSourceOptions {
+    db: Db;
+    /** Chain name used as cache namespace. */
+    chain: string;
+    /** Only cache batches whose range ends at or below this height (avoid caching reorgable data). */
+    finalizedHeight?: () => number | undefined;
+    onEvent?: (event: {
+        type: "hit" | "miss" | "store";
+        fromBlock: number;
+        nextBlock: number;
+    }) => void;
+}
+/**
+ * Wrap any source with a ClickHouse-backed page cache. The wrapped source has
+ * the same interface; ranges already cached are served from the database and
+ * gaps are fetched from the inner source and stored. Cache keys hash the query
+ * shape (filters) so different filter sets never mix.
+ */
+export declare function cached<S extends Source>(inner: S, options: CachedSourceOptions): S;
+/** Hash of the query minus its block range. */
+export declare function hashQuery(query: RangeQuery): string;
+export declare function serializeBatch(batch: unknown): string;
+export declare function reviveBatch(payload: string): unknown;
+export type { EvmSource, BitcoinSource };
+//# sourceMappingURL=cached.d.ts.map

package/dist/sources/cached.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached.d.ts","sourceRoot":"","sources":["../../src/sources/cached.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AAG1C,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAA4B,UAAU,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzG,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,EAAE,CAAC;IACP,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,kGAAkG;IAClG,eAAe,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAC3C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACrG;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,mBAAmB,GAAG,CAAC,CA8DlF;AAED,+CAA+C;AAC/C,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAQnD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAErD;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEpD;AAqBD,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC"}

package/dist/sources/cached.js

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import { sql } from "../db/sql.js";
+import { sourceCache } from "../db/internal.js";
+/**
+ * Wrap any source with a ClickHouse-backed page cache. The wrapped source has
+ * the same interface; ranges already cached are served from the database and
+ * gaps are fetched from the inner source and stored. Cache keys hash the query
+ * shape (filters) so different filter sets never mix.
+ */
+export function cached(inner, options) {
+    const evmInner = inner;
+    const wrapped = {
+        kind: inner.kind,
+        name: `cached(${inner.name})`,
+        getHeight: () => inner.getHeight(),
+        async *fetch(query, fetchOptions) {
+            const queryHash = hashQuery(query);
+            const cachedRanges = await options.db.query(sql `SELECT from_block, next_block FROM ${sourceCache} FINAL
+            WHERE chain = ${options.chain} AND query_hash = ${queryHash}
+              AND from_block >= ${query.fromBlock} AND from_block < ${query.toBlock}
+            ORDER BY from_block`);
+            const ranges = cachedRanges.map((r) => ({ from: Number(r.from_block), next: Number(r.next_block) }));
+            let cursor = query.fromBlock;
+            let ri = 0;
+            while (cursor < query.toBlock) {
+                fetchOptions?.signal?.throwIfAborted();
+                while (ri < ranges.length && ranges[ri].next <= cursor)
+                    ri++;
+                const hit = ranges[ri];
+                if (hit && hit.from === cursor) {
+                    const rows = await options.db.query(sql `SELECT payload FROM ${sourceCache} FINAL WHERE chain = ${options.chain} AND query_hash = ${queryHash} AND from_block = ${cursor} LIMIT 1`);
+                    const payload = rows[0]?.payload;
+                    if (payload) {
+                        const batch = reviveBatch(payload);
+                        const next = Math.min(batch.nextBlock, query.toBlock);
+                        options.onEvent?.({ type: "hit", fromBlock: cursor, nextBlock: next });
+                        yield clampBatch(batch, next);
+                        cursor = next;
+                        continue;
+                    }
+                }
+                // Miss: fetch from inner up to the next cached range start (or the end).
+                let missEnd = query.toBlock;
+                if (hit)
+                    missEnd = Math.min(hit.from, missEnd);
+                options.onEvent?.({ type: "miss", fromBlock: cursor, nextBlock: missEnd });
+                const finalized = options.finalizedHeight?.();
+                for await (const batch of inner.fetch({ ...query, fromBlock: cursor, toBlock: missEnd }, fetchOptions)) {
+                    const b = batch;
+                    if (finalized === undefined || b.nextBlock - 1 <= finalized) {
+                        await options.db.insert(sourceCache).values({
+                            chain: options.chain,
+                            queryHash,
+                            fromBlock: BigInt(b.fromBlock),
+                            nextBlock: BigInt(b.nextBlock),
+                            payload: serializeBatch(b),
+                            createdAt: new Date(),
+                        });
+                        options.onEvent?.({ type: "store", fromBlock: b.fromBlock, nextBlock: b.nextBlock });
+                    }
+                    yield b;
+                    cursor = b.nextBlock;
+                }
+                if (cursor < missEnd)
+                    throw new Error(`cached(${inner.name}): inner source stopped at ${cursor} before ${missEnd}`);
+            }
+        },
+    };
+    if (evmInner.getBlock)
+        wrapped.getBlock = (n) => evmInner.getBlock(n);
+    return wrapped;
+}
+/** Hash of the query minus its block range. */
+export function hashQuery(query) {
+    const { fromBlock: _f, toBlock: _t, ...shape } = query;
+    const json = JSON.stringify(shape, (_k, v) => {
+        if (typeof v === "string")
+            return v.toLowerCase();
+        if (Array.isArray(v) && v.every((x) => typeof x === "string"))
+            return [...v].map((x) => x.toLowerCase()).sort();
+        return v;
+    });
+    return createHash("sha256").update(json).digest("hex").slice(0, 32);
+}
+export function serializeBatch(batch) {
+    return JSON.stringify(batch, tagBigint);
+}
+export function reviveBatch(payload) {
+    return JSON.parse(payload, untagBigint);
+}
+function tagBigint(_key, value) {
+    if (typeof value === "bigint")
+        return { $big: value.toString() };
+    return value;
+}
+function untagBigint(_key, value) {
+    if (value && typeof value === "object" && typeof value.$big === "string")
+        return BigInt(value.$big);
+    return value;
+}
+function clampBatch(batch, next) {
+    if (batch.nextBlock === next)
+        return batch;
+    const b = { ...batch, nextBlock: next };
+    for (const key of ["blocks", "transactions", "logs"]) {
+        if (Array.isArray(b[key]))
+            b[key] = b[key].filter((x) => (x.number ?? x.blockNumber) < next);
+    }
+    return b;
+}
+//# sourceMappingURL=cached.js.map

package/dist/sources/cached.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached.js","sourceRoot":"","sources":["../../src/sources/cached.ts"],"names":[],"mappings":"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"}

package/dist/sources/esplora.d.ts

@@ -0,0 +1,22 @@
+import type { BitcoinSource } from "./types.js";
+export interface EsploraOptions {
+    /** Esplora-compatible base URL: https://mempool.space/api or https://blockstream.info/api (or your own electrs). */
+    url: string;
+    /** Max parallel address scans. Public instances rate-limit aggressively; default 2. */
+    concurrency?: number;
+    /** Extra headers (e.g. API key for a hosted instance). */
+    headers?: Record<string, string>;
+    /** Override fetch (testing). */
+    fetch?: typeof fetch;
+    /** Max transactions per yielded batch. Default 500. */
+    batchSize?: number;
+}
+/**
+ * Bitcoin source backed by an Esplora HTTP API (mempool.space, blockstream.info,
+ * or self-hosted electrs). HyperSync has no Bitcoin support and Bitcoin Core's
+ * RPC has no address index, so address history is scanned through Esplora.
+ * Each query scans the requested addresses newest-first and keeps confirmed
+ * transactions inside [fromBlock, toBlock).
+ */
+export declare function esplora(options: EsploraOptions): BitcoinSource;
+//# sourceMappingURL=esplora.d.ts.map

package/dist/sources/esplora.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esplora.d.ts","sourceRoot":"","sources":["../../src/sources/esplora.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA8B,aAAa,EAAoC,MAAM,YAAY,CAAC;AAE9G,MAAM,WAAW,cAAc;IAC7B,oHAAoH;IACpH,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,gCAAgC;IAChC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAUD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CA4F9D"}