@notuslabs/yail 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thalles Passos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+# yail
+
+**Y**et **A**nother **I**ndexer **L**ibrary. Ponder-style developer experience, [HyperSync](https://docs.envio.dev/docs/HyperSync/overview) as the primary EVM data source, [ClickHouse](https://clickhouse.com) as the only storage.
+
+```sh
+pnpm add @notuslabs/yail          # Node >= 20, ESM
+```
+
+```ts
+// yail.config.ts
+import { createConfig, hypersync, esplora, addressSet } from "@notuslabs/yail";
+import { erc20Abi } from "./abis";
+
+export default createConfig({
+  database: { url: "http://localhost:8123", database: "ledger" },
+  chains: {
+    base: { id: 8453, source: hypersync({ url: "https://base.hypersync.xyz" }), rpc: process.env.BASE_RPC_URL },
+    bitcoin: { id: "bitcoin", source: esplora({ url: "https://mempool.space/api" }) },
+  },
+  contracts: {
+    // Every ERC-20 on Base, but only transfers that touch a registered wallet.
+    Erc20: { abi: erc20Abi, chain: "base", startBlock: 30_000_000,
+      filter: [{ event: "Transfer", args: { from: addressSet("wallets") } }, { event: "Transfer", args: { to: addressSet("wallets") } }] },
+  },
+  accounts: {
+    Wallets: { chain: "base", address: addressSet("wallets"), startBlock: 30_000_000 },
+    BtcWallets: { chain: "bitcoin", address: addressSet("btcWallets"), startBlock: 800_000 },
+  },
+});
+```
+
+```ts
+// src/index.ts
+import { createIndexer } from "@notuslabs/yail";
+import config from "../yail.config";
+import * as schema from "./schema";
+
+export const indexer = createIndexer({ config, schema });
+
+indexer.on("Erc20:Transfer", async ({ event, context }) => {
+  //                                   ^ event.args is typed from the ABI
+  if (context.addresses.has("wallets", event.args.to)) {
+    context.db.insert(schema.ledger).values({ wallet: event.args.to, token: event.address, amount: event.args.value, /* ... */ });
+  }
+});
+
+indexer.on("BtcWallets:transaction", async ({ event }) => {
+  event.received; event.sent; event.fee; // satoshis, typed because the chain is a Bitcoin source
+});
+```
+
+```sh
+yail migrate            # creates database, tables, materialized views
+yail addresses add --set wallets 0xabc…   # queued, backfilled, then live
+yail dev                # index, restart on change; status API on :42069
+```
+
+## Why
+
+| | Ponder | HyperIndex (Envio) | yail |
+|---|---|---|---|
+| Handlers | `ponder.on("C:Event")` | `Contract.Event.handler` | `indexer.on("C:Event")` |
+| Data source | JSON-RPC | HyperSync | HyperSync, JSON-RPC, Esplora (Bitcoin), or a cache in front of any |
+| Storage | Postgres | Postgres | ClickHouse |
+| Dynamic addresses | factory pattern | `contractRegister` | factory pattern **and** runtime address sets with backfill |
+| Re-index one entity | re-sync | re-sync | `yail reindex --scope wallet=0x…` |
+| Tests | — | mocks | replay recorded real data, assert against on-chain ground truth |
+
+Everything the indexer writes is a plain ClickHouse table. An API reads it with the same `sql` tag and typed `db.rows()` the handlers use, or with any ClickHouse client.
+
+## Concepts
+
+### Sources
+
+A source is one interface: `getHeight()` + `fetch(query)` yielding ordered batches of blocks, transactions and logs.
+
+| source | use |
+|---|---|
+| `hypersync({ url, apiToken })` | production EVM. Token from `ENVIO_API_TOKEN` if omitted. |
+| `rpc({ url })` | any JSON-RPC node; slower, no token, used to record fixtures |
+| `esplora({ url })` | Bitcoin address history through mempool.space / blockstream / electrs |
+| `cached(source, { db, chain })` | ClickHouse page cache in front of any source; `cache: { source: true }` in the config does this for every chain |
+| `fixtureSource(fixture)` | replay recorded data in tests |
+
+The runtime only ever indexes blocks `<= head - finality` (default 20 blocks on EVM, 3 on Bitcoin), so reorgs are a non-issue in practice. HyperSync's rollback guard is still checked; on a mismatch the last window is re-indexed automatically.
+
+### Schema
+
+```ts
+import { t, table, materializedView, sql } from "@notuslabs/yail";
+
+export const ledger = table("ledger", {
+  chain: t.string().lowCardinality(),
+  wallet: t.address(),          // lowercase 0x string
+  amount: t.int256(),           // bigint in TS
+  blockTime: t.dateTime(),      // Date in TS
+  note: t.string().nullable(),
+}, {
+  orderBy: ["wallet", "chain", "txHash", "logIndex"], // primary key; duplicates collapse (ReplacingMergeTree)
+  partitionBy: "toYYYYMM(block_time)",
+  scopes: { wallet: "wallet" },                        // enables `reindex --scope wallet=…`
+});
+
+export const daily = table("wallet_daily", { wallet: t.address(), day: t.date(), net: t.int256() },
+  { orderBy: ["wallet", "day"], engine: "SummingMergeTree", indexMeta: false });
+
+export const dailyMv = materializedView("wallet_daily_mv", {
+  from: ledger, to: daily,
+  query: sql`SELECT wallet, toDate(block_time) AS day, sum(amount) AS net FROM ${ledger} GROUP BY wallet, day`,
+});
+```
+
+- Column names are snake_cased in ClickHouse (`blockTime` → `block_time`), keys stay camelCase in TypeScript.
+- Every table gets three hidden columns (`_yail_chain`, `_yail_block`, `_yail_version`). They make re-indexing and versioned dedup work. Opt out with `indexMeta: false` for aggregate targets.
+- Default engine is `ReplacingMergeTree(_yail_version)`: re-inserting a row with the same key (re-run, backfill overlap, crash replay) never double counts. Read with `FINAL` (`db.rows()` does) or let merges settle.
+- Materialized views are first class: created by `yail migrate`, backfilled over existing data with `yail migrate --populate`.
+
+### Handlers
+
+```ts
+indexer.on("Pool:Swap", async ({ event, context }) => {
+  event.args        // typed from the ABI
+  event.log, event.block, event.address, event.transaction /* with includeTransactions: true */
+  context.chain     // { name, id, kind }
+  context.db        // insert (buffered), find (buffer-aware), rows, query, command
+  context.client    // viem readContract with a ClickHouse cache keyed by block (needs `rpc` on the chain)
+  context.http      // fetch with optional ClickHouse cache: http.get(url, { cache: true })
+  context.addresses // has/register/list for address sets
+  context.log       // evlog wide event of the current batch: log.set({ ... })
+});
+indexer.on("Wallets:transaction", ...) // EVM: { transaction, block, address, direction: "from"|"to"|"self" }
+                                      // Bitcoin: { tx, block, address, received, sent, net, fee, isSender }
+indexer.on("setup", ...)              // once per chain before indexing starts
+```
+
+Writes are buffered per source batch and flushed as one INSERT per table before the checkpoint is written. Events are processed in `(block, txIndex, logIndex)` order per chain; chains run concurrently. Only events with a registered handler are fetched from the source.
+
+`context.db.find(table, key)` looks at the current batch's buffer first, then ClickHouse. It is fine for last-value state (a pool's current tick), but the ClickHouse way is to write immutable facts and let `SummingMergeTree`/`AggregatingMergeTree` materialized views maintain aggregates.
+
+### Dynamic addresses and backfill
+
+`addressSet("wallets")` can be used as a contract's `address`, in an event `filter`, or as an account's `address`. Members live in `_yail_addresses` and can be added at any time:
+
+```ts
+await indexer.addresses.register({ set: "wallets", address: "0xabc…", fromBlock: 30_000_000 });
+```
+```sh
+yail addresses add --set wallets 0xabc… 0xdef…
+curl -X POST :42069/addresses -d '{"set":"wallets","address":["0xabc…"]}'
+```
+
+What happens: the live loop adopts the address at its current block `N` and includes it from then on; a job backfills `[fromBlock, N)` with a query restricted to that address; the address flips to `live`. No gaps, no double processing. Progress is visible on `/status` and `/jobs`. Handlers see `context.backfill === true` during the backfill.
+
+`factory({ address, event, parameter })` (Ponder style) discovers child contracts from a factory event; children found inside a batch have their logs fetched for the rest of that batch, so ordering is exact.
+
+### Re-indexing
+
+```sh
+yail reindex --chain base --scope wallet --value 0xabc…      # delete rows where wallet = … in every table declaring that scope, re-run the address history
+yail reindex --chain base --from 30000000 --to 30001000       # delete rows by _yail_block range, re-run the range
+```
+Both go through the same durable job queue (`_yail_jobs`), also reachable via `POST /reindex` and `indexer.reindex()`.
+
+### Caching
+
+- `cache.source` (or wrapping a source in `cached()`): raw source pages stored in `_yail_source_cache`, keyed by query shape. Re-runs with the same filters never hit HyperSync again. Off by default: HyperSync is fast. The key includes the address-set membership at query time, so a set that keeps growing produces new keys; the cache pays off for static filters and for re-running the same state (dev loops, handler fixes).
+- `cache.http` (default on): `context.http.get(url, { cache: true | ttlMs })` persists responses in `_yail_http_cache`. Historical prices and swap classification stay deterministic across re-indexes.
+- `cache.rpc` (default on): `context.client.readContract` results keyed by `(chain, block, to, calldata)` in `_yail_rpc_cache`.
+
+### Observability
+
+Logs are [evlog](https://www.evlog.dev) wide events: one per batch (chain, block range, events, rows, timings) and one per job, plus structured errors with `why`/`fix`. Metrics and traces use the OpenTelemetry API:
+
+| metric | alert on |
+|---|---|
+| `yail.chain.lag_blocks` (gauge, per chain) | growing lag = source or handler problem |
+| `yail.chain.caught_up` | 0 for longer than expected |
+| `yail.errors` (counter, by stage) | any increase |
+| `yail.jobs` (counter, by outcome) | `outcome=failed` |
+| `yail.batch.duration`, `yail.handler.duration`, `yail.flush.duration` | latency histograms |
+| `yail.cache.events` | hit/miss by cache |
+
+Export everything with one call:
+
+```ts
+import { startTelemetry } from "@notuslabs/yail/otel";
+startTelemetry({ serviceName: "wallet-ledger", endpoint: "http://otel-collector:4318" }); // traces + metrics over OTLP/HTTP
+```
+Set `observability.otlpEndpoint` (or `OTEL_EXPORTER_OTLP_ENDPOINT`) to ship logs over OTLP too, and `observability.logsToClickHouse: true` to keep them in `_yail_logs` next to your data (zero extra infrastructure). Recent events are always available at `GET /_evlog/logs`.
+
+HTTP status API (`server.port`, default 42069): `/health`, `/ready` (caught up on every chain), `/status`, `/addresses`, `/reindex`, `/jobs`.
+
+### Testing with real data
+
+```ts
+import { startTestClickHouse, fixtureSource, readFixture } from "@notuslabs/yail/testing";
+
+const ch = await startTestClickHouse();               // YAIL_TEST_CLICKHOUSE_URL or a testcontainer
+const fixture = readFixture("test/fixtures/base-univ3-weth-usdc.json");
+const config = createConfig({ database: ch.database(), chains: { base: { id: 8453, source: fixtureSource(fixture), finality: 0 } }, contracts: { … } });
+const indexer = createIndexer({ config, schema });
+indexer.on("Pool:Swap", …);
+await indexer.run();                                   // index to the fixture height, drain jobs, stop
+expect((await indexer.db.find(poolState, { pool }))!.liquidity).toBe(fixture.expected.liquidity);
+```
+
+Fixtures are recorded from a real chain (`yail record --chain base --from … --to … --out fixture.json`, or `recordEvmFixture` in a script) and can carry `expected` ground truth read at the same block. `packages/yail/test/real-data.test.ts` checks a Uniswap V3 pool's price and liquidity against `slot0()`, USDC wallet deltas against `balanceOf()`, and Bitcoin address totals against Esplora stats.
+
+## CLI
+
+```
+yail start [entry]       run (entry exports the indexer; default src/index.ts)
+yail dev [entry]         run, restart on changes
+yail migrate [entry]     --populate | --reset
+yail reindex [entry]     --chain … (--from … --to … | --scope … --value …)
+yail addresses add|list  --set … [--chain …] [--from-block …]
+yail record [entry]      --chain … --from … --to … --out …
+yail status              --url http://localhost:42069
+```
+
+## Limits and notes
+
+- Bitcoin is scanned per address through Esplora (HyperSync has no Bitcoin, Bitcoin Core has no address index). Fine for wallet sets in the thousands; for more, point `esplora({ url })` at your own electrs.
+- Traces / internal ETH transfers are not indexed (not exposed by HyperSync on most chains without a paid add-on).
+- ClickHouse has no transactions: a crash between a table flush and the checkpoint is repaired by the ReplacingMergeTree key on the next run, so give every table a real identity key.
+- Cross-chain ordering is not enforced (chains are independent loops).

package/bin/yail.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from "../dist/cli/index.js";
+
+run(process.argv.slice(2)).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/addresses/registry.d.ts

@@ -0,0 +1,57 @@
+import type { Db } from "../db/client.js";
+import { addresses as addressesTable } from "../db/internal.js";
+import type { InferRow } from "../schema/table.js";
+export type AddressStatus = "pending" | "backfilling" | "live" | "failed";
+export type AddressRow = InferRow<typeof addressesTable>;
+export interface RegisterInput {
+    set: string;
+    chain: string;
+    address: string;
+    /** First block to index this address from. Defaults to the earliest startBlock using the set on that chain. */
+    fromBlock?: number;
+    meta?: Record<string, unknown>;
+    /** Internal: mark as live immediately (factory children, seeds at genesis). */
+    status?: AddressStatus;
+    adoptedAtBlock?: number;
+}
+/**
+ * In-memory view of `_yail_addresses`, persisted on every change.
+ * Single-writer: the indexer process owns it.
+ */
+export declare class AddressRegistry {
+    private readonly db;
+    private readonly normalize;
+    private rows;
+    private listeners;
+    constructor(db: Db, normalize: (chain: string, address: string) => string);
+    /**
+     * Load rows from the database, merging into memory. A row from the database
+     * only replaces the in-memory one when it is newer, so a refresh racing with
+     * a write made by another chain loop never reverts that write.
+     */
+    load(): Promise<void>;
+    onChange(fn: (row: AddressRow) => void): () => void;
+    get(set: string, chain: string, address: string): AddressRow | undefined;
+    has(set: string, chain: string, address: string): boolean;
+    /** Addresses the live loop should include for a set on a chain (everything adopted). */
+    live(set: string, chain: string): string[];
+    list(filter?: {
+        set?: string;
+        chain?: string;
+        status?: AddressStatus;
+    }): AddressRow[];
+    /** Newly registered addresses on a chain not yet adopted by the live loop. */
+    unadopted(chain: string): AddressRow[];
+    register(input: RegisterInput | RegisterInput[]): Promise<AddressRow[]>;
+    update(set: string, chain: string, address: string, patch: Partial<Pick<AddressRow, "status" | "adopted" | "adoptedAtBlock" | "error" | "fromBlock">>): Promise<AddressRow>;
+    updateMany(rows: AddressRow[], patch: Partial<Pick<AddressRow, "status" | "adopted" | "adoptedAtBlock" | "error">>): Promise<void>;
+    /** Sets that contain an address on a chain (used by scope re-index). */
+    setsContaining(chain: string, address: string): AddressRow[];
+    counts(): Promise<Array<{
+        set: string;
+        chain: string;
+        status: string;
+        count: number;
+    }>>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/addresses/registry.d.ts.map

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

package/dist/addresses/registry.js

@@ -0,0 +1,131 @@
+import { addresses as addressesTable } from "../db/internal.js";
+import { sql } from "../db/sql.js";
+import { toArray } from "../util.js";
+function key(set, chain, address) {
+    return `${set}\u0001${chain}\u0001${address}`;
+}
+/**
+ * In-memory view of `_yail_addresses`, persisted on every change.
+ * Single-writer: the indexer process owns it.
+ */
+export class AddressRegistry {
+    db;
+    normalize;
+    rows = new Map();
+    listeners = new Set();
+    constructor(db, normalize) {
+        this.db = db;
+        this.normalize = normalize;
+    }
+    /**
+     * Load rows from the database, merging into memory. A row from the database
+     * only replaces the in-memory one when it is newer, so a refresh racing with
+     * a write made by another chain loop never reverts that write.
+     */
+    async load() {
+        const rows = await this.db.rows(addressesTable);
+        for (const r of rows) {
+            const k = key(r.set, r.chain, r.address);
+            const existing = this.rows.get(k);
+            if (existing && existing.updatedAt.getTime() > r.updatedAt.getTime())
+                continue;
+            this.rows.set(k, r);
+        }
+    }
+    onChange(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    get(set, chain, address) {
+        return this.rows.get(key(set, chain, this.normalize(chain, address)));
+    }
+    has(set, chain, address) {
+        const r = this.get(set, chain, address);
+        return r !== undefined && r.status !== "failed";
+    }
+    /** Addresses the live loop should include for a set on a chain (everything adopted). */
+    live(set, chain) {
+        const out = [];
+        for (const r of this.rows.values()) {
+            if (r.set === set && r.chain === chain && r.status !== "failed" && r.adopted)
+                out.push(r.address);
+        }
+        return out.sort(); // deterministic order: query shapes (and cache keys) must not depend on load order
+    }
+    list(filter = {}) {
+        return [...this.rows.values()].filter((r) => (!filter.set || r.set === filter.set) && (!filter.chain || r.chain === filter.chain) && (!filter.status || r.status === filter.status));
+    }
+    /** Newly registered addresses on a chain not yet adopted by the live loop. */
+    unadopted(chain) {
+        return [...this.rows.values()].filter((r) => r.chain === chain && !r.adopted && r.status === "pending");
+    }
+    async register(input) {
+        const inputs = toArray(input);
+        const now = new Date();
+        const out = [];
+        for (const i of inputs) {
+            const address = this.normalize(i.chain, i.address);
+            const existing = this.rows.get(key(i.set, i.chain, address));
+            if (existing && existing.status !== "failed") {
+                out.push(existing);
+                continue;
+            }
+            const row = {
+                set: i.set,
+                chain: i.chain,
+                address,
+                status: i.status ?? "pending",
+                fromBlock: BigInt(i.fromBlock ?? 0),
+                adopted: i.adoptedAtBlock !== undefined,
+                adoptedAtBlock: BigInt(i.adoptedAtBlock ?? 0),
+                meta: i.meta ?? {},
+                error: "",
+                registeredAt: existing?.registeredAt ?? now,
+                updatedAt: now,
+            };
+            this.rows.set(key(row.set, row.chain, row.address), row);
+            out.push(row);
+        }
+        const fresh = out.filter((r) => r.updatedAt === now);
+        if (fresh.length > 0)
+            await this.db.insert(addressesTable).values(fresh);
+        for (const r of fresh)
+            for (const l of this.listeners)
+                l(r);
+        return out;
+    }
+    async update(set, chain, address, patch) {
+        const k = key(set, chain, this.normalize(chain, address));
+        const existing = this.rows.get(k);
+        if (!existing)
+            throw new Error(`address ${address} not registered in set ${set} on ${chain}`);
+        const row = { ...existing, ...patch, updatedAt: new Date() };
+        this.rows.set(k, row);
+        await this.db.insert(addressesTable).values(row);
+        for (const l of this.listeners)
+            l(row);
+        return row;
+    }
+    async updateMany(rows, patch) {
+        if (rows.length === 0)
+            return;
+        const now = new Date();
+        const updated = rows.map((r) => ({ ...r, ...patch, updatedAt: now }));
+        for (const r of updated)
+            this.rows.set(key(r.set, r.chain, r.address), r);
+        await this.db.insert(addressesTable).values(updated);
+        for (const r of updated)
+            for (const l of this.listeners)
+                l(r);
+    }
+    /** Sets that contain an address on a chain (used by scope re-index). */
+    setsContaining(chain, address) {
+        const a = this.normalize(chain, address);
+        return [...this.rows.values()].filter((r) => r.chain === chain && r.address === a);
+    }
+    async counts() {
+        const rows = await this.db.query(sql `SELECT set, chain, status, count() AS count FROM ${addressesTable} FINAL GROUP BY set, chain, status ORDER BY set, chain, status`);
+        return rows.map((r) => ({ ...r, count: Number(r.count) }));
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/addresses/registry.js.map

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

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+export declare function run(argv: string[]): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AA4BA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwHvD"}