univo 0.1.18 → 0.2.0

package/dist/cli.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
-import WS from 'ws';
+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, v as version, l as name } from './shared/univo.mtzSyY24.mjs';
+import { http } from './transport.mjs';
+import { c as createLogger, v as version, g as name } from './shared/univo.HDazcQ9A.mjs';
+import './shared/univo.C0flyVee.mjs';
 
 const log = createLogger({ quiet: false });
 const dev = defineCommand({
@@ -24,39 +25,39 @@ const dev = defineCommand({
       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: [] })
+        client.request({ method: "private_getEvents", params: [] }),
+        client.request({ 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,
+        events,
+        metadata,
         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) => {
+      const ws$1 = new WebSocket(url, [], { WebSocket: ws });
+      ws$1.binaryType = "arraybuffer";
+      ws$1.onerror = (event) => log.error(event.message);
+      ws$1.onopen = () => log.info(`Dev server started for ${ctx.args.url}`);
+      ws$1.onclose = () => log.info(`Dev server closed for ${ctx.args.url}`);
+      ws$1.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));
+          ws$1.send(JSON.stringify(response));
         } catch (error) {
           const response = { jsonrpc: "2.0", id: null, error: { code: 0, message: "Invalid request" } };
-          ws.send(JSON.stringify(response));
+          ws$1.send(JSON.stringify(response));
         }
       };
     } catch (error) {
-      if (error instanceof Error) return log.error(error.message);
+      if (error instanceof Error) {
+        return log.error(error.message);
+      }
       throw error;
     }
   }

package/dist/index.d.mts

@@ -1,50 +1,118 @@
-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];
-};
+import { Storage } from 'unstorage';
 
+/**
+ * Block -----------------------------------------------------------------------------------------------------------------------------------
+ */
 type Block = {
     eth_chainId: `0x${string}`;
-    eth_getBlockByHash: {
+    eth_getBlockByNumber: {
         hash: `0x${string}`;
         number: `0x${string}`;
+        parentHash: `0x${string}`;
     };
     eth_getBlockReceipts: Array<{
+        blockHash: `0x${string}`;
         logs: Array<{
             address: `0x${string}`;
             topics: `0x${string}`[];
         }>;
     }>;
 };
+/**
+ * Filters -----------------------------------------------------------------------------------------------------------------------------------
+ */
 type Filter = {
-    /** The chain id */
+    /** Index blocks with this chain id */
     chain: number;
-    /** Block to querying/listening from */
+    /** Index blocks from this start block (inclusive) */
     fromBlock: number;
-    /** Block to query/listen until  */
+    /** Index blocks until this stop block (inclusive)  */
     toBlock?: number;
-    /** The event */
+    /** Index blocks where this event topic was emitted */
     event?: `0x${string}`;
-    /** The contract address from which logs should originate */
+    /** Index blocks that involve this address */
     address?: `0x${string}`;
 };
 declare function matchFilter(block: Block, filter: Filter): boolean;
+/**
+ * Events -----------------------------------------------------------------------------------------------------------------------------------
+ */
 type Event<TBlock, TEvent> = {
-    /** Human-readable identifier for the event */
+    /**
+     * A human-readable identifier for the event.
+     */
     id: string;
-    /** The set of filters that determines if the handler should execute for a given block */
+    /**
+     * Filters let you define what specific blocks you want this event to index.
+     *
+     * Blockchains are massive datasets and most of the time we are only ever interested in small portions of it.
+     * Sometimes that can be specific events like ERC20 transfers and other times it could be all events emitted
+     * by a specific contract. Filters provide a simple way for an event to define exactly which blocks we want
+     * to index.
+     *
+     * Filters reduce costs and improve backfill performance by ensuring we only index the blocks we need and
+     * ignore the blocks that don't have the data we are interested in.
+     *
+     * By default your event will not index any blocks, you must opt-in to indexing by providing atleast one filter.
+     *
+     * Each property in the filter operates like an AND statement. For example, if you specifiy an `address` and
+     * an `event` it implies that you only want to index blocks where the specific `address` emitted the specific
+     * `event` topic provided.
+     *
+     * However, when multiple filters are defined for a given event those filters operate like an OR statement. For
+     * example, if we define a second filter looking for a different `address` and `event` our event will now index
+     * any block that matches either the first filter or the second filter.
+     *
+     * Note that filters are a rudimentary method to dramatically reduce the number of blocks your application needs
+     * to index. Any advanced filtering should be performed in the event `handler` itself.
+     */
     filters: Filter[];
-    /** The handler that transforms a block into a list of events */
+    /**
+     * Synchronously transforms a raw block into a list of events.
+     *
+     * When a block matches any of filters defined by your event it will be passed to this function to be synchronously
+     * transformed into a list of structured events.
+     *
+     * The shape of the input `block` is determined by the return value of `getBlock` function provided to your `indexer`.
+     *
+     * The returned output value should be an array containg any valid JavaScript values. Each event that you return from
+     * your handler should not depend on any information outside of the input block data. It should directly map a given
+     * input (the raw block) to a given output (structured events). This ensures that handler remains idempotent and that
+     * repeated calls with the same input block produce the same output events.
+     */
     handler: (block: TBlock) => TEvent[];
-    /** Persist storage */
+    /**
+     * Storage adapter to persist events in your off-chain storage.
+     */
     storage: {
+        /**
+         * Upserts a batch of events into your storage system.
+         *
+         * After a block is transformed into a list of structured events by your `handler` function, that batch
+         * is passed to this `upsert` function so they can be upserted into your storage system.
+         *
+         * This function must be idempotent. Functionally, this means that if the same batch of events is upserted
+         * multiple times it only produces a single set of events in your storage system.
+         */
         upsert: (events: TEvent[]) => Promise<void>;
+        /**
+         * Deletes a batch of events from your storage system.
+         *
+         * When your indexer encounters a chain reorganisation, this `delete` function will be invoked with the
+         * same batch of events created by that reorganised block. This ensures that any events that were previously
+         * upserted into your storage system that are no longer part of the canonical chain are safely removed.
+         */
+        delete?: (events: TEvent[]) => Promise<void>;
     };
 };
+/**
+ * Indexer -----------------------------------------------------------------------------------------------------------------------------------
+ */
 type Head = {
     hash: `0x${string}`;
     chain: `0x${string}`;
     number: `0x${string}`;
+    parentHash: `0x${string}`;
 };
 type Metadata = {
     version: string;
@@ -60,49 +128,62 @@ type Result = {
 };
 type IndexerOptions<TBlock> = {
     /**
+     * Silences all logs including errors.
+     *
      * 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
+     *
+     * Facilitates secure communication with a trusted source like the univo dashboard.
      */
     signingKey: string;
     /**
-     * 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.
+     * Storage interface for durably persisting indexer metadata.
+     *
+     * This uses the unified key-value storage API from unstorage. Install the `unstorage` dependency
+     * and provide the return value of your `createStorage()` call. Check out the documentation for
+     * a full list of [supported storage drivers](https://unstorage.unjs.io/drivers).
+     *
+     * Functionally, storing metadata is fundamental to ensure the correct operation of your indexer. It
+     * ensures that you indexer recovers from downtime and ensures that all blocks are processed correctly during
+     * chain reorganisations.
+     */
+    metadataStorage: Storage;
+    /**
+     * Loads raw block data in realtime from a trusted set of RPC sources.
+     *
+     * Note that historical backfills do not use this function to load block data.
+     *
+     * The response from this function determines the input data to your `handler` functions in each event.
+     * Generally, the shape is a list of RPC methods with their corresponding value from an RPC node. This
+     * generic format allows you support the full range of RPC data available to you from your node. This
+     * flexibility is important in cases where some methods are supported on specific chains only.
+     *
+     * Note that there is a minimum set of RPC methods expected on the response notably `eth_chainId`,
+     * `eth_getBlockByNumber` and `eth_getBlockReceipts`. These are expected so that we can safely match
+     * each block processed against your event filters.
+     *
+     * Note that we provide only the block number to look up block data. During a chain reorganisation, this
+     * makes it possible for different RPC calls to return data for different block hashes. We manually verify
+     * that all methods return the expected block hash. However, for any custom methods you add you must manually
+     * verify the block hash is consistent with the other known methods.
      */
-    getBlock: (block: Head) => Promise<TBlock>;
+    getBlock: (block: {
+        chain: `0x${string}`;
+        number: string;
+    }) => Promise<TBlock | null>;
 };
 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 };
+export type { Block, Event, Filter, Head, Indexer, Metadata, Result };

package/dist/index.d.ts

@@ -1,50 +1,118 @@
-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];
-};
+import { Storage } from 'unstorage';
 
+/**
+ * Block -----------------------------------------------------------------------------------------------------------------------------------
+ */
 type Block = {
     eth_chainId: `0x${string}`;
-    eth_getBlockByHash: {
+    eth_getBlockByNumber: {
         hash: `0x${string}`;
         number: `0x${string}`;
+        parentHash: `0x${string}`;
     };
     eth_getBlockReceipts: Array<{
+        blockHash: `0x${string}`;
         logs: Array<{
             address: `0x${string}`;
             topics: `0x${string}`[];
         }>;
     }>;
 };
+/**
+ * Filters -----------------------------------------------------------------------------------------------------------------------------------
+ */
 type Filter = {
-    /** The chain id */
+    /** Index blocks with this chain id */
     chain: number;
-    /** Block to querying/listening from */
+    /** Index blocks from this start block (inclusive) */
     fromBlock: number;
-    /** Block to query/listen until  */
+    /** Index blocks until this stop block (inclusive)  */
     toBlock?: number;
-    /** The event */
+    /** Index blocks where this event topic was emitted */
     event?: `0x${string}`;
-    /** The contract address from which logs should originate */
+    /** Index blocks that involve this address */
     address?: `0x${string}`;
 };
 declare function matchFilter(block: Block, filter: Filter): boolean;
+/**
+ * Events -----------------------------------------------------------------------------------------------------------------------------------
+ */
 type Event<TBlock, TEvent> = {
-    /** Human-readable identifier for the event */
+    /**
+     * A human-readable identifier for the event.
+     */
     id: string;
-    /** The set of filters that determines if the handler should execute for a given block */
+    /**
+     * Filters let you define what specific blocks you want this event to index.
+     *
+     * Blockchains are massive datasets and most of the time we are only ever interested in small portions of it.
+     * Sometimes that can be specific events like ERC20 transfers and other times it could be all events emitted
+     * by a specific contract. Filters provide a simple way for an event to define exactly which blocks we want
+     * to index.
+     *
+     * Filters reduce costs and improve backfill performance by ensuring we only index the blocks we need and
+     * ignore the blocks that don't have the data we are interested in.
+     *
+     * By default your event will not index any blocks, you must opt-in to indexing by providing atleast one filter.
+     *
+     * Each property in the filter operates like an AND statement. For example, if you specifiy an `address` and
+     * an `event` it implies that you only want to index blocks where the specific `address` emitted the specific
+     * `event` topic provided.
+     *
+     * However, when multiple filters are defined for a given event those filters operate like an OR statement. For
+     * example, if we define a second filter looking for a different `address` and `event` our event will now index
+     * any block that matches either the first filter or the second filter.
+     *
+     * Note that filters are a rudimentary method to dramatically reduce the number of blocks your application needs
+     * to index. Any advanced filtering should be performed in the event `handler` itself.
+     */
     filters: Filter[];
-    /** The handler that transforms a block into a list of events */
+    /**
+     * Synchronously transforms a raw block into a list of events.
+     *
+     * When a block matches any of filters defined by your event it will be passed to this function to be synchronously
+     * transformed into a list of structured events.
+     *
+     * The shape of the input `block` is determined by the return value of `getBlock` function provided to your `indexer`.
+     *
+     * The returned output value should be an array containg any valid JavaScript values. Each event that you return from
+     * your handler should not depend on any information outside of the input block data. It should directly map a given
+     * input (the raw block) to a given output (structured events). This ensures that handler remains idempotent and that
+     * repeated calls with the same input block produce the same output events.
+     */
     handler: (block: TBlock) => TEvent[];
-    /** Persist storage */
+    /**
+     * Storage adapter to persist events in your off-chain storage.
+     */
     storage: {
+        /**
+         * Upserts a batch of events into your storage system.
+         *
+         * After a block is transformed into a list of structured events by your `handler` function, that batch
+         * is passed to this `upsert` function so they can be upserted into your storage system.
+         *
+         * This function must be idempotent. Functionally, this means that if the same batch of events is upserted
+         * multiple times it only produces a single set of events in your storage system.
+         */
         upsert: (events: TEvent[]) => Promise<void>;
+        /**
+         * Deletes a batch of events from your storage system.
+         *
+         * When your indexer encounters a chain reorganisation, this `delete` function will be invoked with the
+         * same batch of events created by that reorganised block. This ensures that any events that were previously
+         * upserted into your storage system that are no longer part of the canonical chain are safely removed.
+         */
+        delete?: (events: TEvent[]) => Promise<void>;
     };
 };
+/**
+ * Indexer -----------------------------------------------------------------------------------------------------------------------------------
+ */
 type Head = {
     hash: `0x${string}`;
     chain: `0x${string}`;
     number: `0x${string}`;
+    parentHash: `0x${string}`;
 };
 type Metadata = {
     version: string;
@@ -60,49 +128,62 @@ type Result = {
 };
 type IndexerOptions<TBlock> = {
     /**
+     * Silences all logs including errors.
+     *
      * 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
+     *
+     * Facilitates secure communication with a trusted source like the univo dashboard.
      */
     signingKey: string;
     /**
-     * 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.
+     * Storage interface for durably persisting indexer metadata.
+     *
+     * This uses the unified key-value storage API from unstorage. Install the `unstorage` dependency
+     * and provide the return value of your `createStorage()` call. Check out the documentation for
+     * a full list of [supported storage drivers](https://unstorage.unjs.io/drivers).
+     *
+     * Functionally, storing metadata is fundamental to ensure the correct operation of your indexer. It
+     * ensures that you indexer recovers from downtime and ensures that all blocks are processed correctly during
+     * chain reorganisations.
+     */
+    metadataStorage: Storage;
+    /**
+     * Loads raw block data in realtime from a trusted set of RPC sources.
+     *
+     * Note that historical backfills do not use this function to load block data.
+     *
+     * The response from this function determines the input data to your `handler` functions in each event.
+     * Generally, the shape is a list of RPC methods with their corresponding value from an RPC node. This
+     * generic format allows you support the full range of RPC data available to you from your node. This
+     * flexibility is important in cases where some methods are supported on specific chains only.
+     *
+     * Note that there is a minimum set of RPC methods expected on the response notably `eth_chainId`,
+     * `eth_getBlockByNumber` and `eth_getBlockReceipts`. These are expected so that we can safely match
+     * each block processed against your event filters.
+     *
+     * Note that we provide only the block number to look up block data. During a chain reorganisation, this
+     * makes it possible for different RPC calls to return data for different block hashes. We manually verify
+     * that all methods return the expected block hash. However, for any custom methods you add you must manually
+     * verify the block hash is consistent with the other known methods.
      */
-    getBlock: (block: Head) => Promise<TBlock>;
+    getBlock: (block: {
+        chain: `0x${string}`;
+        number: string;
+    }) => Promise<TBlock | null>;
 };
 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 };
+export type { Block, Event, Filter, Head, Indexer, Metadata, Result };