univo 0.3.2 → 0.4.0

package/dist/shared/univo.CEA4vY0E.d.ts

@@ -0,0 +1,354 @@
+import { RpcBlock, RpcTransactionReceipt } from 'viem';
+import { Storage } from '../metadata.js';
+
+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 = {
+    /**
+     * All available methods that can be requested
+     */
+    request: Record<string, any>;
+    /**
+     * All available event types to subscribe to a stream of values
+     */
+    subscribe: Record<string, any>;
+};
+/**
+ * Indexer -----------------------------------------------------------------------------------------------------------------------------------
+ */
+type IndexerRpc = {
+    request: {
+        /**
+         * Accepts a chain identifier
+         * @returns Height of the last finalized block indexed
+         */
+        public_getFinalizedHeight: (chain: `0x${string}`) => Promise<number>;
+        /**
+         * Accepts a reorganised block and deletes all related events from storage
+         */
+        public_deleteReorganisedHead: (head: Head) => Promise<void>;
+        /**
+         * Accepts an unfinalized head and writes all events to storage
+         */
+        public_writeUnfinalizedHead: (head: Head) => Promise<void>;
+        /**
+         * Accepts a chain identifier and caches its current finalized height
+         */
+        public_writeFinalizedHeight: (chain: `0x${string}`) => Promise<void>;
+        /**
+         * Accepts a finalized head and executes all actions
+         */
+        public_writeFinalizedHead: (head: Head) => Promise<void>;
+        /**
+         * Accepts a chain identifier and finalizes the indexer
+         */
+        public_finalize: (chain: `0x${string}`) => Promise<void>;
+        /**
+         * @returns Specified metadata about the indexer
+         */
+        private_getMetadata: () => Promise<Metadata>;
+        /**
+         * @returns All events defined on this indexer
+         */
+        private_getEvents: () => Promise<{
+            id: string;
+            filters: Flatten<Filter>[];
+        }[]>;
+        /**
+         * Accepts a list of events and a batch of minified block data and writes to storage
+         * @returns A list of failures that occured for each event and block pair
+         */
+        private_writeEvents: (params: {
+            events: string[];
+            blocks: Block[];
+        }) => Promise<{
+            failures: Result[];
+        }>;
+        /**
+         * Accepts a block head and writes events to storage
+         * @returns A list of results and block keys that were accessed as those events were written to storage
+         */
+        private_writeEventsAndGetKeys: (params: {
+            events: string[];
+            head: Head;
+        }) => Promise<{
+            results: Result[];
+            keys: string[];
+        }>;
+    };
+    subscribe: Record<string, never>;
+};
+
+/**
+ * Types -----------------------------------------------------------------------------------------------------------------------------------
+ */
+type Protocol = "http" | "wss" | "local";
+type Transport<R extends Rpc, P extends Protocol = Protocol> = {
+    /**
+     * The underlying transport protocol.
+     */
+    protocol: P;
+    /**
+     * Performs an RPC request
+     * @returns The RPC response
+     */
+    request: <M extends keyof R["request"]>(opts: {
+        method: M;
+        signal?: AbortSignal;
+        params: Parameters<R["request"][M]>;
+    }) => Promise<Awaited<ReturnType<R["request"][M]>>>;
+    /**
+     * Subscribes to specific event to receive and invoke a callback for a stream of values
+     * @returns An async function to unsubscribe from the stream
+     */
+    subscribe: <M extends keyof R["subscribe"]>(param: M, handler: (message: R["subscribe"][M]) => void) => Promise<() => Promise<void>>;
+};
+/**
+ * Local -----------------------------------------------------------------------------------------------------------------------------------
+ */
+declare function local<R extends Rpc>(rpc: R): Transport<R, "local">;
+declare function wss<R extends Rpc>(url: string, opts?: {
+    quiet?: boolean;
+}): Transport<R, "wss">;
+/**
+ * HTTP -----------------------------------------------------------------------------------------------------------------------------------
+ */
+declare function http<R extends Rpc>(url: string, opts?: {
+    signingKey?: string;
+}): Transport<R, "http">;
+
+/**
+ * The minimum RPC data required to process a block.
+ *
+ * Extend this interface in your application to expose additional RPC methods to every event:
+ *
+ * ```ts
+ * import "univo";
+ *
+ * declare module "univo" {
+ *   interface Block {
+ *     eth_getBalance: `0x${string}`;
+ *   }
+ * }
+ * ```
+ *
+ * Your `getBlock` function must also return any required fields added by the augmentation.
+ */
+interface Block {
+    eth_chainId: `0x${string}`;
+    eth_getBlockByNumber: RpcBlock<"latest", true>;
+    eth_getBlockReceipts: RpcTransactionReceipt[];
+}
+/**
+ * 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<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 input uses the shared `Block` interface. Extend it with `declare module "univo"` in your application
+     * to expose additional RPC methods returned by your indexer's `getBlock` function.
+     *
+     * 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: Block) => 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>;
+    };
+};
+declare function defineEvent<TEvent = unknown>(event: Event<TEvent>): Event<TEvent>;
+/**
+ * Actions -----------------------------------------------------------------------------------------------------------------------------------
+ */
+type Action<TEvent> = {
+    /**
+     * A human-readable identifier for the action.
+     */
+    id: string;
+    /**
+     * The on-chain event that should invoke this action.
+     */
+    event: Event<TEvent>;
+    /**
+     * The action you want to execute when the event _finalizes_ 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).
+     *
+     * Actions can be 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 handle retries.
+     *
+     * Actions operate with at-least-once delivery. This means that your actions may be invoked
+     * multiple times. It is important that your handler is resilient to this by making use of an
+     * idempotency key (usually the identifier in the event passed to your handler). We guarantee
+     * that the indexer will not finalize a given block until it achieves a non-erroring execution
+     * from your action.
+     */
+    handler: (event: TEvent) => Promise<void> | void;
+};
+declare function defineAction<TEvent>(action: Action<TEvent>): Action<TEvent>;
+/**
+ * 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 AnyEvent = Omit<Event<any>, "storage"> & {
+    storage: {
+        upsert(events: any[]): Promise<void>;
+        delete(events: any[]): Promise<void>;
+    };
+};
+type AnyAction = Omit<Action<any>, "event" | "handler"> & {
+    event: AnyEvent;
+    handler(event: any): Promise<void> | void;
+};
+type Indexer = {
+    /**
+     * 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;
+    /**
+     * Events
+     */
+    events: AnyEvent[];
+    /**
+     * Actions
+     */
+    actions: AnyAction[];
+    /**
+     * Storage interface for durably persisting indexer metadata.
+     *
+     * 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. Additional methods may be returned. Remember to
+     * extend the shared `Block` interface using `declare module "univo"` in your application.
+     *
+     * 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: `0x${string}` | "finalized";
+    }) => Promise<Block>;
+};
+declare function defineIndexer(opts: Indexer): Transport<IndexerRpc, "local">;
+
+export { defineEvent as a, defineAction as b, defineIndexer as d, http as h, local as l, wss as w };
+export type { Action as A, Block as B, Event as E, Filter as F, Head as H, IndexerRpc as I, Metadata as M, Rpc as R, Transport as T, Indexer as c, Result as e };