@provex/utils 1.0.16 → 1.2.3

package/dist/src/ids.js

@@ -1,81 +1,231 @@
-import { concatHex, keccak256, numberToHex, stringToHex } from "viem";
+/**
+ * @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,
-    participant: onChainAddress,
+    /** Provider hash ID: keccak256(chainId || providerHash) */
     providerHash: onChainHash,
+    /** Verifier ID: keccak256(chainId || verifierAddress) */
     verifier: onChainAddress,
-    depositVerifierAdded: ({ depositId, verifier }) => {
-        return keccak256(concatHex([depositId, verifier]));
-    },
-    depositCurrencyAdded: ({ depositId, currency, verifier }) => {
-        return keccak256(concatHex([
-            ids.depositVerifierAdded({ verifier, depositId }),
-            currency,
-        ]));
-    },
-    depositConversionRateUpdated: ({ currency, verifier, depositId, changeId }) => {
-        return concatHex([
-            ids.depositCurrencyAdded({ currency, verifier, depositId }),
-            numberToHex(changeId, { size: 4 }),
-        ]);
-    },
 };
 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: ({ chainId, depositId }) => concatHex([
-        numberToHex(depositId, { size: 8 }),
-        numberToHex(chainId, { size: 4 }),
-    ]),
-    block: ({ timestamp, chainId }) => concatHex([
-        numberToHex(timestamp, { size: 8 }),
-        numberToHex(chainId, { size: 4 }),
-    ]),
-    transaction: ({ timestamp, chainId, transactionIndex }) => concatHex([
-        numberToHex(timestamp, { size: 8 }),
-        numberToHex(transactionIndex, { size: 4 }),
-        numberToHex(chainId, { size: 4 }),
-    ]),
-    log: ({ timestamp, chainId, transactionIndex, logIndex }) => concatHex([
-        numberToHex(timestamp, { size: 8 }),
-        numberToHex(transactionIndex, { size: 4 }),
-        numberToHex(logIndex, { size: 4 }),
-        numberToHex(chainId, { size: 4 }),
-    ]),
-    order: ({ 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 }),
-    ]),
-    stat: ({ timestamp, type, action, currency, verifier, token, chainId }) => {
-        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(action), token, currency ?? '0x', verifier])).slice(26)}`,
+    /**
+     * 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/src/ids.test.d.ts

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