univo 0.1.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 univo
+
+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,27 @@
+# univo
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+
+Blazing-fast, developer-friendly blockchain indexing software designed to help you extract, transform, and load historical and realtime blockchain data into your own storage systems at scale.
+
+![univo](https://univo.app/img/univo.svg)
+
+Conceptually, indexing software is responsible for synchronising data between a blockchain and some other storage system. The end goal is that your off-chain storage always accurately reflects the latest on-chain state.
+
+univo was forged from years of experience building and maintaining blockchain indexers across the Ethereum ecosystem. It is designed to fit into your existing application and ensures that indexing blockchains remains simple, fast, and affordable as your application grows in scale and complexity.
+
+## Documentation
+
+Visit [univo.app](https://univo.app/docs) for documentation, guides, and the API reference.
+
+## License
+
+univo is MIT-licensed open-source software.
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/univo?style=flat&colorA=18181B&colorB=F0DB4F
+[npm-version-href]: https://npmjs.com/package/univo
+[npm-downloads-src]: https://img.shields.io/npm/dm/univo?style=flat&colorA=18181B&colorB=F0DB4F
+[npm-downloads-href]: https://npmjs.com/package/univo

package/dist/cli.d.mts

@@ -0,0 +1 @@
+

package/dist/cli.d.ts

@@ -0,0 +1 @@
+

package/dist/cli.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import WS from 'ws';
+import open from 'open';
+import { config } from 'dotenv';
+import { WebSocket } from 'partysocket';
+import { defineCommand, runMain } from 'citty';
+import { http } from './client.mjs';
+import { c as createLogger, e as version, l as name } from './shared/univo.rTUTP64t.mjs';
+
+const log = createLogger({ quiet: false });
+const dev = defineCommand({
+  args: {
+    url: {
+      required: true,
+      type: "positional",
+      description: "Endpoint url like http://localhost:3000"
+    }
+  },
+  async run(ctx) {
+    try {
+      if (!ctx.args.url.startsWith("http://")) throw new Error("`url` must start with http://");
+      config();
+      const localSigningKey = process.env.UNIVO_SIGNING_KEY;
+      if (localSigningKey === void 0) throw new Error("Please provide a UNIVO_SIGNING_KEY environment variable");
+      const client = http(ctx.args.url, { signingKey: localSigningKey });
+      const [events, metadata] = await Promise.all([
+        client.request({ jsonrpc: "2.0", id: 0, method: "private_getEvents", params: [] }),
+        client.request({ jsonrpc: "2.0", id: 0, method: "private_getMetadata", params: [] })
+      ]);
+      if (events.error) throw new Error(`Failed to connect to ${ctx.args.url}. Check that your server is running on the correct port.`);
+      if (metadata.error) throw new Error(`Failed to connect to ${ctx.args.url}. Check that your server is running on the correct port.`);
+      const remoteSigningKey = crypto.randomUUID();
+      const url = `https://tunnel-univo.app/v1/${crypto.randomUUID()}`;
+      const endpoint = {
+        url,
+        events: events.result,
+        metadata: metadata.result,
+        signing_key: remoteSigningKey
+      };
+      const data = btoa(JSON.stringify(endpoint));
+      await open(`https://univo.app/dev/${data}`);
+      const ws = new WebSocket(url, [], { WebSocket: WS });
+      ws.binaryType = "arraybuffer";
+      ws.onerror = (event) => log.error(event.message);
+      ws.onopen = () => log.info(`Dev server started for ${ctx.args.url}`);
+      ws.onclose = () => log.info(`Dev server closed for ${ctx.args.url}`);
+      ws.onmessage = async (event) => {
+        try {
+          const request = JSON.parse(event.data);
+          log.info(`Received request ${request.id}:${request.method}`);
+          const response = await client.request(request);
+          ws.send(JSON.stringify(response));
+        } catch (error) {
+          const response = { jsonrpc: "2.0", id: null, error: { code: 0, message: "Invalid request" } };
+          ws.send(JSON.stringify(response));
+        }
+      };
+    } catch (error) {
+      if (error instanceof Error) return log.error(error.message);
+      throw error;
+    }
+  }
+});
+const main = defineCommand({
+  subCommands: { dev },
+  meta: { name, version }
+});
+runMain(main).catch((error) => {
+  if (error instanceof Error) log.error(error.message);
+  process.exit(1);
+});

package/dist/client.d.mts

@@ -0,0 +1,24 @@
+import { Rpc } from './index.mjs';
+
+type Request<M extends keyof Rpc> = {
+    jsonrpc: "2.0";
+    id: number;
+    method: M;
+    params: Parameters<Rpc[M]>;
+};
+type Response<M extends keyof Rpc> = {
+    jsonrpc: "2.0";
+    id: number;
+    result?: Awaited<ReturnType<Rpc[M]>>;
+    error?: {
+        code: number;
+        message: string;
+    };
+};
+declare function http(url: string, opts?: {
+    signingKey?: string;
+}): {
+    request<M extends keyof Rpc>({ jsonrpc, id, method, params }: Request<M>): Promise<Response<M>>;
+};
+
+export { http };

package/dist/client.d.ts

@@ -0,0 +1,24 @@
+import { Rpc } from './index.js';
+
+type Request<M extends keyof Rpc> = {
+    jsonrpc: "2.0";
+    id: number;
+    method: M;
+    params: Parameters<Rpc[M]>;
+};
+type Response<M extends keyof Rpc> = {
+    jsonrpc: "2.0";
+    id: number;
+    result?: Awaited<ReturnType<Rpc[M]>>;
+    error?: {
+        code: number;
+        message: string;
+    };
+};
+declare function http(url: string, opts?: {
+    signingKey?: string;
+}): {
+    request<M extends keyof Rpc>({ jsonrpc, id, method, params }: Request<M>): Promise<Response<M>>;
+};
+
+export { http };

package/dist/client.mjs

@@ -0,0 +1,43 @@
+import { a as createException, o as compress, f as getSignature, g as getException } from './shared/univo.rTUTP64t.mjs';
+
+const MIN_GZIP_SIZE = 1024;
+function http(url, opts = {}) {
+  return {
+    async request({ jsonrpc, id, method, params }) {
+      try {
+        let body = JSON.stringify({ jsonrpc, id, method, params });
+        const headers = new Headers();
+        headers.set("Content-Type", "application/json");
+        if (method.startsWith("private_")) {
+          if (opts.signingKey === void 0) throw new Error(ClientUnauthorizedError);
+          if (body.length > MIN_GZIP_SIZE) {
+            body = await compress(body).catch((cause) => {
+              throw new Error(ClientCompressionError, { cause });
+            });
+            headers.set("Content-Encoding", "gzip");
+          }
+          const signature = await getSignature({ key: opts.signingKey, body }).catch((cause) => {
+            throw new Error(ClientSignatureError, { cause });
+          });
+          headers.set("X-Univo-Signature", signature);
+        }
+        const res = await fetch(url, { headers, body, method: "POST" }).catch((cause) => {
+          throw new Error(ClientConnectionError, { cause });
+        });
+        return await res.json().catch((cause) => {
+          throw new Error(ClientResponseError, { cause });
+        });
+      } catch (error) {
+        const message = getException(error) || "Unknown RPC error";
+        return { jsonrpc, id, error: { code: 0, message } };
+      }
+    }
+  };
+}
+const ClientCompressionError = createException("An error occurred when compressing the request");
+const ClientConnectionError = createException("An errored occurred when connecting to the server");
+const ClientResponseError = createException("An error occurred when reading the servers response");
+const ClientSignatureError = createException("An error occurred with the outgoing request signature");
+const ClientUnauthorizedError = createException("Attempted to execute a private method without providing a request signing key");
+
+export { http };

package/dist/index.d.mts

@@ -0,0 +1,113 @@
+type CamelToSnake<T extends string, P extends string = ""> = string extends T ? string : T extends `${infer C0}${infer R}` ? CamelToSnake<R, `${P}${C0 extends Lowercase<C0> ? "" : "_"}${Lowercase<C0>}`> : P;
+type Flatten<T> = {
+    [K in keyof T as CamelToSnake<Extract<K, string>>]: T[K];
+};
+
+type Block = {
+    eth_chainId: `0x${string}`;
+    eth_getBlockByHash: {
+        hash: `0x${string}`;
+        number: `0x${string}`;
+    };
+    eth_getBlockReceipts: Array<{
+        logs: Array<{
+            address: `0x${string}`;
+            topics: `0x${string}`[];
+        }>;
+    }>;
+};
+type Filter = {
+    /** The chain id */
+    chain: number;
+    /** Block to querying/listening from */
+    fromBlock: number;
+    /** Block to query/listen until  */
+    toBlock?: number;
+    /** The event */
+    event?: `0x${string}`;
+    /** The contract address from which logs should originate */
+    address?: `0x${string}`;
+};
+declare function matchFilter(block: Block, filter: Filter): boolean;
+type Event<TBlock, TEvent> = {
+    /** Human-readable identifier for the event */
+    id: string;
+    /** The set of filters that determines if the handler should execute for a given block */
+    filters: Filter[];
+    /** The handler that transforms a block into a list of events */
+    handler: (block: TBlock) => TEvent[];
+    /** Persist storage */
+    storage: {
+        upsert: (events: TEvent[]) => Promise<void>;
+    };
+};
+type Head = {
+    hash: `0x${string}`;
+    chain: `0x${string}`;
+    number: `0x${string}`;
+};
+type Metadata = {
+    version: string;
+    language: string;
+    max_concurrency: number | undefined;
+};
+type Result = {
+    status: string;
+    event_id: string;
+    chain: `0x${string}`;
+    block_hash: `0x${string}`;
+    block_number: `0x${string}`;
+    created_at: number;
+};
+type IndexerOptions<TBlock> = {
+    /**
+     * Logs are emitted based on the environment LOG_LEVEL. Set `quiet: true` to surpress all logs.
+     * Available log options are `DEBUG`, `INFO`, `WARN`, and `ERROR`.
+     */
+    quiet?: boolean;
+    /**
+     * Request signing key
+     */
+    signingKey: string;
+    /**
+     * Maximum number of concurrent connections to open when backfilling blocks
+     */
+    maxConcurrency?: number;
+    /**
+     * This function is to load each block when indexing blocks in realtime. This ensures that all block
+     * data processed originates from a trusted RPC source and can be safely relied on.
+     */
+    getBlock: (block: Head) => Promise<TBlock>;
+};
+type Indexer<TBlock> = {
+    fetch: (req: Request) => Promise<Response>;
+    event: <TEvent>(event: Event<TBlock, TEvent>) => Event<TBlock, TEvent>;
+};
+type Rpc = {
+    public_writeBlocks(endpoint: string, heads: Head[]): Promise<void>;
+    private_getMetadata(): Promise<Metadata>;
+    private_getEvents(): Promise<{
+        id: string;
+        filters: Flatten<Filter>[];
+    }[]>;
+    private_writeEvents(params: {
+        events: string[];
+        blocks: Block[];
+    }): Promise<{
+        failures: Result[];
+    }>;
+    private_writeEventsAndGetKeys(params: {
+        events: string[];
+        block: Block;
+    }): Promise<{
+        results: Result[];
+        keys: string[];
+    }>;
+};
+declare function indexer<TBlock extends Block>(opts: IndexerOptions<TBlock>): {
+    fetch: (req: Request) => Promise<Response>;
+    event: <TEvent>(event: Event<TBlock, TEvent>) => Event<TBlock, TEvent>;
+};
+
+export { indexer, matchFilter };
+export type { Event, Indexer, Rpc };

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+type CamelToSnake<T extends string, P extends string = ""> = string extends T ? string : T extends `${infer C0}${infer R}` ? CamelToSnake<R, `${P}${C0 extends Lowercase<C0> ? "" : "_"}${Lowercase<C0>}`> : P;
+type Flatten<T> = {
+    [K in keyof T as CamelToSnake<Extract<K, string>>]: T[K];
+};
+
+type Block = {
+    eth_chainId: `0x${string}`;
+    eth_getBlockByHash: {
+        hash: `0x${string}`;
+        number: `0x${string}`;
+    };
+    eth_getBlockReceipts: Array<{
+        logs: Array<{
+            address: `0x${string}`;
+            topics: `0x${string}`[];
+        }>;
+    }>;
+};
+type Filter = {
+    /** The chain id */
+    chain: number;
+    /** Block to querying/listening from */
+    fromBlock: number;
+    /** Block to query/listen until  */
+    toBlock?: number;
+    /** The event */
+    event?: `0x${string}`;
+    /** The contract address from which logs should originate */
+    address?: `0x${string}`;
+};
+declare function matchFilter(block: Block, filter: Filter): boolean;
+type Event<TBlock, TEvent> = {
+    /** Human-readable identifier for the event */
+    id: string;
+    /** The set of filters that determines if the handler should execute for a given block */
+    filters: Filter[];
+    /** The handler that transforms a block into a list of events */
+    handler: (block: TBlock) => TEvent[];
+    /** Persist storage */
+    storage: {
+        upsert: (events: TEvent[]) => Promise<void>;
+    };
+};
+type Head = {
+    hash: `0x${string}`;
+    chain: `0x${string}`;
+    number: `0x${string}`;
+};
+type Metadata = {
+    version: string;
+    language: string;
+    max_concurrency: number | undefined;
+};
+type Result = {
+    status: string;
+    event_id: string;
+    chain: `0x${string}`;
+    block_hash: `0x${string}`;
+    block_number: `0x${string}`;
+    created_at: number;
+};
+type IndexerOptions<TBlock> = {
+    /**
+     * Logs are emitted based on the environment LOG_LEVEL. Set `quiet: true` to surpress all logs.
+     * Available log options are `DEBUG`, `INFO`, `WARN`, and `ERROR`.
+     */
+    quiet?: boolean;
+    /**
+     * Request signing key
+     */
+    signingKey: string;
+    /**
+     * Maximum number of concurrent connections to open when backfilling blocks
+     */
+    maxConcurrency?: number;
+    /**
+     * This function is to load each block when indexing blocks in realtime. This ensures that all block
+     * data processed originates from a trusted RPC source and can be safely relied on.
+     */
+    getBlock: (block: Head) => Promise<TBlock>;
+};
+type Indexer<TBlock> = {
+    fetch: (req: Request) => Promise<Response>;
+    event: <TEvent>(event: Event<TBlock, TEvent>) => Event<TBlock, TEvent>;
+};
+type Rpc = {
+    public_writeBlocks(endpoint: string, heads: Head[]): Promise<void>;
+    private_getMetadata(): Promise<Metadata>;
+    private_getEvents(): Promise<{
+        id: string;
+        filters: Flatten<Filter>[];
+    }[]>;
+    private_writeEvents(params: {
+        events: string[];
+        blocks: Block[];
+    }): Promise<{
+        failures: Result[];
+    }>;
+    private_writeEventsAndGetKeys(params: {
+        events: string[];
+        block: Block;
+    }): Promise<{
+        results: Result[];
+        keys: string[];
+    }>;
+};
+declare function indexer<TBlock extends Block>(opts: IndexerOptions<TBlock>): {
+    fetch: (req: Request) => Promise<Response>;
+    event: <TEvent>(event: Event<TBlock, TEvent>) => Event<TBlock, TEvent>;
+};
+
+export { indexer, matchFilter };
+export type { Event, Indexer, Rpc };