@provex/utils 1.0.16 → 1.2.4

package/dist/ids.d.ts

@@ -0,0 +1,175 @@
+/**
+ * @fileoverview ID generation and parsing utilities for the indexer.
+ *
+ * The indexer uses composite IDs (orderIds) to uniquely identify and order
+ * events across multiple chains. Each ID type encodes different information:
+ *
+ * - **deposit**: [escrow (20)][localId (8)][chainId (4)] = 32 bytes
+ * - **block**: [timestamp (8)][chainId (4)] = 12 bytes
+ * - **transaction**: [timestamp (8)][txIndex (4)][chainId (4)] = 16 bytes
+ * - **log**: [timestamp (8)][txIndex (4)][logIndex (4)][chainId (4)] = 20 bytes
+ * - **order**: [timestamp (8)][txIndex (4)][eventType (1)][logIndex (4)][chainId (4)] = 21 bytes
+ * - **stat**: [timestamp (8)][hash (20)][chainId (4)] = 32 bytes
+ *
+ * @remarks
+ * The orderId structure ensures:
+ * - Global ordering across chains by timestamp
+ * - Deterministic ordering within same block
+ * - Parseability to extract original components
+ *
+ * @see {@link events} for event type definitions
+ * @see {@link depositKeys} for deposit compound keys
+ */
+import { type Hex } from "viem";
+import { type EventType } from "./events.js";
+import { type TimeResolutionKey } from "./time.js";
+import type { StatEvent } from "./stats.js";
+import { type ChainId } from "./chain.js";
+/** Input parameters for provider hash generation */
+export type ProviderHashInputs = {
+    chainId: bigint | number;
+    hash: Hex;
+};
+/** Input parameters for on-chain hash generation */
+export type OnChainHashInputs = {
+    chainId: bigint | number;
+    hash: Hex;
+};
+/** Input parameters for on-chain address hashing */
+export type OnChainAddressInputs = {
+    chainId: bigint | number;
+    address: Hex;
+};
+/**
+ * Generate a chain-specific hash by combining chainId and an existing hash.
+ * Creates a unique identifier that includes chain context.
+ */
+export declare const onChainHash: ({ chainId, hash }: OnChainHashInputs) => `0x${string}`;
+export declare const onChainAddress: ({ chainId, address }: OnChainAddressInputs) => `0x${string}`;
+/**
+ * ID generator functions for various entity types.
+ * Each function creates a unique, deterministic identifier.
+ */
+export declare const ids: {
+    /** Block ID: keccak256(chainId || blockHash) */
+    block: ({ chainId, hash }: OnChainHashInputs) => `0x${string}`;
+    /** Transaction ID: keccak256(chainId || txHash) */
+    transaction: ({ chainId, hash }: OnChainHashInputs) => `0x${string}`;
+    /** Provider hash ID: keccak256(chainId || providerHash) */
+    providerHash: ({ chainId, hash }: OnChainHashInputs) => `0x${string}`;
+    /** Verifier ID: keccak256(chainId || verifierAddress) */
+    verifier: ({ chainId, address }: OnChainAddressInputs) => `0x${string}`;
+};
+export type OrderIdInputs = {
+    timestamp: bigint;
+    chainId: bigint;
+};
+export type OrderIdTransactionInputs = OrderIdInputs & {
+    transactionIndex: bigint;
+};
+export type OrderIdLogInputs = OrderIdTransactionInputs & {
+    logIndex: bigint;
+};
+export type OrderIdOrderInputs = OrderIdLogInputs & {
+    name: EventType;
+};
+export type DepositIdInputs = {
+    chainId: bigint | number;
+    escrow: Hex;
+    depositId: bigint | number;
+};
+export type LogStatsIdInputs = {
+    timestamp: bigint;
+    type: TimeResolutionKey;
+    event: StatEvent;
+    currency: Hex | null;
+    token: Hex;
+    verifier: Hex;
+    chainId: bigint | number;
+    version: 'v2' | 'v3';
+};
+/**
+ * Chunk a hex string into parts of specified byte sizes
+ * @param input - The hex string to chunk (with 0x prefix)
+ * @param byteSizes - Array of byte sizes for each chunk
+ * @returns Array of hex strings, one for each chunk
+ */
+export declare function chunkHex<T extends readonly number[]>(input: Hex, byteSizes: T): {
+    [K in keyof T]: Hex;
+};
+/**
+ * OrderId serialization and parsing utilities.
+ *
+ * Each orderId type has a `serialize` method to create the ID from components,
+ * and a `parse` method to extract components from an existing ID.
+ *
+ * @example
+ * ```ts
+ * // Create a deposit orderId
+ * const id = orderId.deposit.serialize({ chainId: 8453n, escrow, depositId: 42n })
+ *
+ * // Parse it back
+ * const { chainId, escrow, depositId } = orderId.deposit.parse(id)
+ * ```
+ */
+export declare const orderId: {
+    /**
+     * Deposit orderId: uniquely identifies a deposit across all chains and escrows.
+     * Format: [escrow (20)][localId (8)][chainId (4)] = 32 bytes
+     */
+    deposit: {
+        serialize: ({ chainId, escrow, depositId }: DepositIdInputs) => `0x${string}`;
+        parse: (id: Hex) => {
+            escrow: Hex;
+            depositId: bigint;
+            chainId: ChainId;
+        };
+    };
+    block: {
+        serialize: ({ timestamp, chainId }: OrderIdInputs) => `0x${string}`;
+        parse: (id: Hex) => {
+            timestamp: bigint;
+            chainId: ChainId;
+        };
+    };
+    transaction: {
+        serialize: ({ timestamp, chainId, transactionIndex }: OrderIdTransactionInputs) => `0x${string}`;
+        parse: (id: Hex) => {
+            timestamp: bigint;
+            transactionIndex: number;
+            chainId: ChainId;
+        };
+    };
+    log: {
+        serialize: ({ timestamp, chainId, transactionIndex, logIndex }: OrderIdLogInputs) => `0x${string}`;
+        parse: (id: Hex) => {
+            timestamp: bigint;
+            transactionIndex: number;
+            logIndex: number;
+            chainId: ChainId;
+        };
+    };
+    order: {
+        serialize: ({ timestamp, chainId, transactionIndex, logIndex, name }: OrderIdOrderInputs) => `0x${string}`;
+        parse: (id: Hex) => {
+            timestamp: bigint;
+            transactionIndex: number;
+            eventTypeId: number;
+            name?: EventType;
+            logIndex: number;
+            chainId: ChainId;
+        };
+    };
+    stat: {
+        serialize: ({ timestamp, type, event, currency, verifier, token, chainId, version }: LogStatsIdInputs) => `0x${string}`;
+        /**
+         * Parse a stat orderId to extract timestamp and chainId.
+         * Note: The hash component cannot be reversed to get type/event/currency/verifier/token.
+         * Format: [timestamp (8)][hash (20)][chainId (4)] = 32 bytes
+         */
+        parse: (id: Hex) => {
+            timestamp: bigint;
+            chainId: ChainId;
+        };
+    };
+};

package/dist/ids.js

@@ -0,0 +1,231 @@
+/**
+ * @fileoverview ID generation and parsing utilities for the indexer.
+ *
+ * The indexer uses composite IDs (orderIds) to uniquely identify and order
+ * events across multiple chains. Each ID type encodes different information:
+ *
+ * - **deposit**: [escrow (20)][localId (8)][chainId (4)] = 32 bytes
+ * - **block**: [timestamp (8)][chainId (4)] = 12 bytes
+ * - **transaction**: [timestamp (8)][txIndex (4)][chainId (4)] = 16 bytes
+ * - **log**: [timestamp (8)][txIndex (4)][logIndex (4)][chainId (4)] = 20 bytes
+ * - **order**: [timestamp (8)][txIndex (4)][eventType (1)][logIndex (4)][chainId (4)] = 21 bytes
+ * - **stat**: [timestamp (8)][hash (20)][chainId (4)] = 32 bytes
+ *
+ * @remarks
+ * The orderId structure ensures:
+ * - Global ordering across chains by timestamp
+ * - Deterministic ordering within same block
+ * - Parseability to extract original components
+ *
+ * @see {@link events} for event type definitions
+ * @see {@link depositKeys} for deposit compound keys
+ */
+import { concatHex, keccak256, numberToHex, stringToHex, isHex } from "viem";
+import { eventOrderId } from "./events.js";
+import { interval } from "./time.js";
+import { chainIds } from "./chain.js";
+/**
+ * Generate a chain-specific hash by combining chainId and an existing hash.
+ * Creates a unique identifier that includes chain context.
+ */
+export const onChainHash = ({ chainId, hash }) => (keccak256(concatHex([
+    numberToHex(chainId, { size: 8 }),
+    hash,
+])));
+export const onChainAddress = ({ chainId, address }) => (onChainHash({ chainId, hash: address }));
+/**
+ * ID generator functions for various entity types.
+ * Each function creates a unique, deterministic identifier.
+ */
+export const ids = {
+    /** Block ID: keccak256(chainId || blockHash) */
+    block: onChainHash,
+    /** Transaction ID: keccak256(chainId || txHash) */
+    transaction: onChainHash,
+    /** Provider hash ID: keccak256(chainId || providerHash) */
+    providerHash: onChainHash,
+    /** Verifier ID: keccak256(chainId || verifierAddress) */
+    verifier: onChainAddress,
+};
+const hourFactor = BigInt(interval.hour) / BigInt(interval.second);
+const dayFactor = BigInt(interval.day) / BigInt(interval.second);
+const monthFactor = BigInt(interval.month) / BigInt(interval.second);
+/**
+ * Chunk a hex string into parts of specified byte sizes
+ * @param input - The hex string to chunk (with 0x prefix)
+ * @param byteSizes - Array of byte sizes for each chunk
+ * @returns Array of hex strings, one for each chunk
+ */
+export function chunkHex(input, byteSizes) {
+    const expectedBytes = byteSizes.reduce((a, b) => a + b, 0);
+    if (!isHex(input, { strict: true })) {
+        throw new Error(`Invalid hex input: ${input}`);
+    }
+    const hex = input.slice(2).toLowerCase();
+    const expectedHexLen = expectedBytes * 2;
+    if (hex.length !== expectedHexLen) {
+        throw new Error(`Hex length ${hex.length / 2} bytes does not match expected ${expectedHexLen / 2} bytes`);
+    }
+    const out = [];
+    let offset = 0;
+    for (const size of byteSizes) {
+        const chars = size * 2;
+        const part = "0x" + hex.slice(offset, offset + chars);
+        out.push(part);
+        offset += chars;
+    }
+    return out;
+}
+/**
+ * Type guard to check if a number is a valid ChainId
+ */
+function isChainId(value) {
+    return chainIds.includes(value);
+}
+/**
+ * OrderId serialization and parsing utilities.
+ *
+ * Each orderId type has a `serialize` method to create the ID from components,
+ * and a `parse` method to extract components from an existing ID.
+ *
+ * @example
+ * ```ts
+ * // Create a deposit orderId
+ * const id = orderId.deposit.serialize({ chainId: 8453n, escrow, depositId: 42n })
+ *
+ * // Parse it back
+ * const { chainId, escrow, depositId } = orderId.deposit.parse(id)
+ * ```
+ */
+export const orderId = {
+    /**
+     * Deposit orderId: uniquely identifies a deposit across all chains and escrows.
+     * Format: [escrow (20)][localId (8)][chainId (4)] = 32 bytes
+     */
+    deposit: {
+        serialize: ({ chainId, escrow, depositId }) => concatHex([
+            escrow,
+            numberToHex(depositId, { size: 8 }),
+            numberToHex(chainId, { size: 4 }),
+        ]),
+        parse: (id) => {
+            const [escrow, depositIdHex, chainIdHex] = chunkHex(id, [20, 8, 4]);
+            const depositId = BigInt(depositIdHex);
+            const chainIdNum = Number(BigInt(chainIdHex));
+            if (!isChainId(chainIdNum)) {
+                throw new Error(`Unknown chainId parsed from deposit id: ${chainIdNum}`);
+            }
+            return { escrow, depositId, chainId: chainIdNum };
+        },
+    },
+    block: {
+        serialize: ({ timestamp, chainId }) => concatHex([
+            numberToHex(timestamp, { size: 8 }),
+            numberToHex(chainId, { size: 4 }),
+        ]),
+        parse: (id) => {
+            const [timestampHex, chainIdHex] = chunkHex(id, [8, 4]);
+            const timestamp = BigInt(timestampHex);
+            const chainIdNum = Number(BigInt(chainIdHex));
+            if (!isChainId(chainIdNum)) {
+                throw new Error(`Unknown chainId parsed from block id: ${chainIdNum}`);
+            }
+            return { timestamp, chainId: chainIdNum };
+        },
+    },
+    transaction: {
+        serialize: ({ timestamp, chainId, transactionIndex }) => concatHex([
+            numberToHex(timestamp, { size: 8 }),
+            numberToHex(transactionIndex, { size: 4 }),
+            numberToHex(chainId, { size: 4 }),
+        ]),
+        parse: (id) => {
+            const [timestampHex, txIndexHex, chainIdHex] = chunkHex(id, [8, 4, 4]);
+            const timestamp = BigInt(timestampHex);
+            const transactionIndex = Number(BigInt(txIndexHex));
+            const chainIdNum = Number(BigInt(chainIdHex));
+            if (!isChainId(chainIdNum)) {
+                throw new Error(`Unknown chainId parsed from transaction id: ${chainIdNum}`);
+            }
+            return { timestamp, transactionIndex, chainId: chainIdNum };
+        },
+    },
+    log: {
+        serialize: ({ timestamp, chainId, transactionIndex, logIndex }) => concatHex([
+            numberToHex(timestamp, { size: 8 }),
+            numberToHex(transactionIndex, { size: 4 }),
+            numberToHex(logIndex, { size: 4 }),
+            numberToHex(chainId, { size: 4 }),
+        ]),
+        parse: (id) => {
+            const [timestampHex, txIndexHex, logIndexHex, chainIdHex] = chunkHex(id, [8, 4, 4, 4]);
+            const timestamp = BigInt(timestampHex);
+            const transactionIndex = Number(BigInt(txIndexHex));
+            const logIndex = Number(BigInt(logIndexHex));
+            const chainIdNum = Number(BigInt(chainIdHex));
+            if (!isChainId(chainIdNum)) {
+                throw new Error(`Unknown chainId parsed from log id: ${chainIdNum}`);
+            }
+            return { timestamp, transactionIndex, logIndex, chainId: chainIdNum };
+        },
+    },
+    order: {
+        serialize: ({ timestamp, chainId, transactionIndex, logIndex, name }) => concatHex([
+            numberToHex(timestamp, { size: 8 }),
+            numberToHex(transactionIndex, { size: 4 }),
+            numberToHex(eventOrderId.get(name), { size: 1 }),
+            numberToHex(logIndex, { size: 4 }),
+            numberToHex(chainId, { size: 4 }),
+        ]),
+        parse: (id) => {
+            const [timestampHex, txIndexHex, typeHex, logIndexHex, chainIdHex] = chunkHex(id, [8, 4, 1, 4, 4]);
+            const timestamp = BigInt(timestampHex);
+            const transactionIndex = Number(BigInt(txIndexHex));
+            const eventTypeId = Number(BigInt(typeHex));
+            const logIndex = Number(BigInt(logIndexHex));
+            const chainIdNum = Number(BigInt(chainIdHex));
+            if (!isChainId(chainIdNum)) {
+                throw new Error(`Unknown chainId parsed from order id: ${chainIdNum}`);
+            }
+            const typeEntries = Array.from(eventOrderId.entries());
+            const name = typeEntries.find(([, v]) => v === eventTypeId)?.[0];
+            return { timestamp, transactionIndex, eventTypeId, name, logIndex, chainId: chainIdNum };
+        },
+    },
+    stat: {
+        serialize: ({ timestamp, type, event, currency, verifier, token, chainId, version }) => {
+            const hour = (timestamp / hourFactor) * hourFactor;
+            const day = (timestamp / dayFactor) * dayFactor;
+            const month = (timestamp / monthFactor) * monthFactor;
+            let time = timestamp;
+            if (type === "hour") {
+                time = hour;
+            }
+            if (type === "day") {
+                time = day;
+            }
+            if (type === "month") {
+                time = month;
+            }
+            return concatHex([
+                numberToHex(time, { size: 8 }),
+                `0x${keccak256(concatHex([stringToHex(type), stringToHex(event), token, currency ?? '0x', verifier, stringToHex(version)])).slice(26)}`,
+                numberToHex(chainId, { size: 4 }),
+            ]);
+        },
+        /**
+         * Parse a stat orderId to extract timestamp and chainId.
+         * Note: The hash component cannot be reversed to get type/event/currency/verifier/token.
+         * Format: [timestamp (8)][hash (20)][chainId (4)] = 32 bytes
+         */
+        parse: (id) => {
+            const [timestampHex, , chainIdHex] = chunkHex(id, [8, 20, 4]);
+            const timestamp = BigInt(timestampHex);
+            const chainIdNum = Number(BigInt(chainIdHex));
+            if (!isChainId(chainIdNum)) {
+                throw new Error(`Unknown chainId parsed from stat id: ${chainIdNum}`);
+            }
+            return { timestamp, chainId: chainIdNum };
+        },
+    },
+};

package/dist/ids.test.d.ts

@@ -0,0 +1 @@
+export {};