univo 0.2.18 → 0.2.19

package/dist/rpc.d.mts

@@ -1,5 +1,9 @@
-import { H as Head, M as Metadata, F as Flatten, a as Filter, B as Block, R as Result } from './shared/univo.BNqa7KED.mjs';
-import '@storagesdk/core';
+import { Storage } from '@storagesdk/core';
+
+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 Rpc = {
     /**
@@ -98,4 +102,246 @@ type IndexerRpc = {
     subscribe: Record<string, never>;
 };
 
-export type { IndexerRpc, NodeRpc, Rpc };
+/**
+ * Block -----------------------------------------------------------------------------------------------------------------------------------
+ */
+type Block = {
+    eth_chainId: `0x${string}`;
+    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 = {
+    /** Index blocks with this chain id */
+    chain: number;
+    /** Index blocks from this start block (inclusive) */
+    fromBlock: number;
+    /** Index blocks until this stop block (inclusive)  */
+    toBlock?: number;
+    /** Index blocks where this event topic was emitted */
+    event?: `0x${string}`;
+    /** Index blocks that involve this address */
+    address?: `0x${string}`;
+};
+/**
+ * Events -----------------------------------------------------------------------------------------------------------------------------------
+ */
+type Event<TBlock, TEvent> = {
+    /**
+     * A human-readable identifier for the event.
+     */
+    id: string;
+    /**
+     * 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[];
+    /**
+     * 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[];
+    /**
+     * 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>;
+    };
+};
+/**
+ * Actions -----------------------------------------------------------------------------------------------------------------------------------
+ */
+type Action<TBlock, TEvent> = {
+    /**
+     * A human-readable identifier for the action.
+     */
+    id: string;
+    /**
+     * The on-chain event that should invoke this action.
+     */
+    event: Event<TBlock, TEvent>;
+    /**
+     * The action you want to execute when the event occurs on-chain.
+     *
+     * Actions are processed during realtime indexing only and are never invoked during historical
+     * backfills. Common actions include payment notifications for confirming payments or customer
+     * deposits, transaction monitoring for KYC/AML compliance tracking, DeFi protocol monitoring,
+     * or wallet activity notifications or alerts.
+     *
+     * Actions may be invoked multiple times. It is important that your application code is
+     * resilient to this by making use of an idempotency key - usually the id of the event passed
+     * to your handler.
+     *
+     * In production, actions should perform lightweight processing only. Do not use them for
+     * long-running tasks. Actions are extremely powerful when combined with a durable execution
+     * framework like Temporal, Inngest, Trigger.dev, Cloudflare Workflows, or Restate.dev to
+     * perform more advanced workflows that allow you to chain together multiple steps and
+     * automatically handle retries.
+     */
+    handler: {
+        /**
+         * Executes your action when the event first occurs on-chain.
+         *
+         * Latest handlers operate with best-effort delivery. If your handler throws an error it will be
+         * retried 2 and then ignored. If you need to guarantee that your latest handler is invoked
+         * successfully you should run the same action code again from a finalized handler.
+         */
+        latest?: (event: TEvent) => Promise<void> | void;
+        /**
+         * Executes your action when the event finalizes on-chain.
+         *
+         * Finalized handlers operate with at-least-once delivery. We guarantee that the indexer
+         * will not finalize a given block until it receives a successful response from your action.
+         */
+        finalized?: (event: TEvent) => Promise<void> | void;
+    };
+};
+/**
+ * Indexer -----------------------------------------------------------------------------------------------------------------------------------
+ */
+type Head = {
+    hash: `0x${string}`;
+    chain: `0x${string}`;
+    number: `0x${string}`;
+    parent_hash: `0x${string}`;
+};
+type Metadata = {
+    version: string;
+    language: string;
+};
+type Result = {
+    status: string;
+    event_id: string;
+    hash: `0x${string}`;
+    chain: `0x${string}`;
+    number: `0x${string}`;
+    parent_hash: `0x${string}`;
+    created_at: number;
+};
+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;
+    /**
+     * 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: {
+        chain: `0x${string}`;
+        number: string;
+    }) => Promise<TBlock | null>;
+};
+type Indexer<TBlock> = {
+    /**
+     * A web standard HTTP request handler. This is the entrypoint to your indexer and allows it to be deployed
+     * to your framework of choice so that it can receive requests and process responses.
+     */
+    fetch: (req: Request) => Promise<Response>;
+    /**
+     * Define on-chain events you want to record in your off-chain storage system.
+     */
+    event: <TEvent>(event: Event<TBlock, TEvent>) => Event<TBlock, TEvent>;
+    /**
+     * Perform fire-and-forget effects in response to on-chain events.
+     */
+    action: <TEvent>(action: Action<TBlock, TEvent>) => Action<TBlock, TEvent>;
+};
+declare function indexer<TBlock extends Block>(opts: IndexerOptions<TBlock>): Indexer<TBlock> & IndexerRpc;
+
+export { indexer as i };
+export type { Block as B, Event as E, Filter as F, Head as H, Indexer as I, IndexerRpc, Metadata as M, NodeRpc, Result as R, Rpc };

package/dist/rpc.d.ts

@@ -1,5 +1,9 @@
-import { H as Head, M as Metadata, F as Flatten, a as Filter, B as Block, R as Result } from './shared/univo.BNqa7KED.js';
-import '@storagesdk/core';
+import { Storage } from '@storagesdk/core';
+
+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 Rpc = {
     /**
@@ -98,4 +102,246 @@ type IndexerRpc = {
     subscribe: Record<string, never>;
 };
 
-export type { IndexerRpc, NodeRpc, Rpc };
+/**
+ * Block -----------------------------------------------------------------------------------------------------------------------------------
+ */
+type Block = {
+    eth_chainId: `0x${string}`;
+    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 = {
+    /** Index blocks with this chain id */
+    chain: number;
+    /** Index blocks from this start block (inclusive) */
+    fromBlock: number;
+    /** Index blocks until this stop block (inclusive)  */
+    toBlock?: number;
+    /** Index blocks where this event topic was emitted */
+    event?: `0x${string}`;
+    /** Index blocks that involve this address */
+    address?: `0x${string}`;
+};
+/**
+ * Events -----------------------------------------------------------------------------------------------------------------------------------
+ */
+type Event<TBlock, TEvent> = {
+    /**
+     * A human-readable identifier for the event.
+     */
+    id: string;
+    /**
+     * 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[];
+    /**
+     * 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[];
+    /**
+     * 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>;
+    };
+};
+/**
+ * Actions -----------------------------------------------------------------------------------------------------------------------------------
+ */
+type Action<TBlock, TEvent> = {
+    /**
+     * A human-readable identifier for the action.
+     */
+    id: string;
+    /**
+     * The on-chain event that should invoke this action.
+     */
+    event: Event<TBlock, TEvent>;
+    /**
+     * The action you want to execute when the event occurs on-chain.
+     *
+     * Actions are processed during realtime indexing only and are never invoked during historical
+     * backfills. Common actions include payment notifications for confirming payments or customer
+     * deposits, transaction monitoring for KYC/AML compliance tracking, DeFi protocol monitoring,
+     * or wallet activity notifications or alerts.
+     *
+     * Actions may be invoked multiple times. It is important that your application code is
+     * resilient to this by making use of an idempotency key - usually the id of the event passed
+     * to your handler.
+     *
+     * In production, actions should perform lightweight processing only. Do not use them for
+     * long-running tasks. Actions are extremely powerful when combined with a durable execution
+     * framework like Temporal, Inngest, Trigger.dev, Cloudflare Workflows, or Restate.dev to
+     * perform more advanced workflows that allow you to chain together multiple steps and
+     * automatically handle retries.
+     */
+    handler: {
+        /**
+         * Executes your action when the event first occurs on-chain.
+         *
+         * Latest handlers operate with best-effort delivery. If your handler throws an error it will be
+         * retried 2 and then ignored. If you need to guarantee that your latest handler is invoked
+         * successfully you should run the same action code again from a finalized handler.
+         */
+        latest?: (event: TEvent) => Promise<void> | void;
+        /**
+         * Executes your action when the event finalizes on-chain.
+         *
+         * Finalized handlers operate with at-least-once delivery. We guarantee that the indexer
+         * will not finalize a given block until it receives a successful response from your action.
+         */
+        finalized?: (event: TEvent) => Promise<void> | void;
+    };
+};
+/**
+ * Indexer -----------------------------------------------------------------------------------------------------------------------------------
+ */
+type Head = {
+    hash: `0x${string}`;
+    chain: `0x${string}`;
+    number: `0x${string}`;
+    parent_hash: `0x${string}`;
+};
+type Metadata = {
+    version: string;
+    language: string;
+};
+type Result = {
+    status: string;
+    event_id: string;
+    hash: `0x${string}`;
+    chain: `0x${string}`;
+    number: `0x${string}`;
+    parent_hash: `0x${string}`;
+    created_at: number;
+};
+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;
+    /**
+     * 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: {
+        chain: `0x${string}`;
+        number: string;
+    }) => Promise<TBlock | null>;
+};
+type Indexer<TBlock> = {
+    /**
+     * A web standard HTTP request handler. This is the entrypoint to your indexer and allows it to be deployed
+     * to your framework of choice so that it can receive requests and process responses.
+     */
+    fetch: (req: Request) => Promise<Response>;
+    /**
+     * Define on-chain events you want to record in your off-chain storage system.
+     */
+    event: <TEvent>(event: Event<TBlock, TEvent>) => Event<TBlock, TEvent>;
+    /**
+     * Perform fire-and-forget effects in response to on-chain events.
+     */
+    action: <TEvent>(action: Action<TBlock, TEvent>) => Action<TBlock, TEvent>;
+};
+declare function indexer<TBlock extends Block>(opts: IndexerOptions<TBlock>): Indexer<TBlock> & IndexerRpc;
+
+export { indexer as i };
+export type { Block as B, Event as E, Filter as F, Head as H, Indexer as I, IndexerRpc, Metadata as M, NodeRpc, Result as R, Rpc };