@formo/analytics 1.26.0 → 1.28.0

package/dist/esm/src/wagmi/WagmiEventHandler.js

@@ -54,6 +54,42 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
 };
 import { SignatureStatus, TransactionStatus } from "../types/events";
 import { logger } from "../logger";
+import { encodeWriteContractData, concatCalldataWithSuffix, extractFunctionArgs, buildSafeFunctionArgs, } from "./utils";
+import { extractBuilderCodes } from "../utils/builderCode";
+/**
+ * Built-in transaction fields that could collide with function args.
+ * Defined at module level to avoid recreating on every method call.
+ */
+var RESERVED_FIELDS = new Set([
+    "status",
+    "chainId",
+    "address",
+    "data",
+    "to",
+    "value",
+    "transactionHash",
+    "function_name",
+    "function_args",
+    "builder_codes",
+]);
+/**
+ * Clean up old entries from a Set to prevent memory leaks.
+ * Removes oldest entries when size exceeds maxSize.
+ *
+ * @param set - The Set to clean up
+ * @param maxSize - Maximum allowed size before cleanup (default: 1000)
+ * @param removeCount - Number of entries to remove (default: 500)
+ */
+function cleanupOldEntries(set, maxSize, removeCount) {
+    if (maxSize === void 0) { maxSize = 1000; }
+    if (removeCount === void 0) { removeCount = 500; }
+    if (set.size > maxSize) {
+        var entries = Array.from(set);
+        for (var i = 0; i < removeCount && i < entries.length; i++) {
+            set.delete(entries[i]);
+        }
+    }
+}
 var WagmiEventHandler = /** @class */ (function () {
     function WagmiEventHandler(formoAnalytics, wagmiConfig, queryClient) {
         this.unsubscribers = [];
@@ -65,15 +101,26 @@ var WagmiEventHandler = /** @class */ (function () {
          * Key format: `${mutationId}:${status}`
          */
         this.processedMutations = new Set();
+        /**
+         * Track processed query states to prevent duplicate event emissions
+         * Key format: `${queryHash}:${status}`
+         */
+        this.processedQueries = new Set();
+        /**
+         * Store transaction details from BROADCASTED events for use in CONFIRMED/REVERTED
+         * Key: transactionHash, Value: transaction details including the original sender address
+         */
+        this.pendingTransactions = new Map();
         this.formo = formoAnalytics;
         this.wagmiConfig = wagmiConfig;
         this.queryClient = queryClient;
         logger.info("WagmiEventHandler: Initializing Wagmi integration");
         // Set up connection/disconnection/chain listeners
         this.setupConnectionListeners();
-        // Set up mutation tracking if QueryClient is provided
+        // Set up mutation and query tracking if QueryClient is provided
         if (this.queryClient) {
             this.setupMutationTracking();
+            this.setupQueryTracking();
         }
         else {
             logger.warn("WagmiEventHandler: QueryClient not provided, signature and transaction events will not be tracked");
@@ -223,6 +270,131 @@ var WagmiEventHandler = /** @class */ (function () {
         this.unsubscribers.push(unsubscribe);
         logger.info("WagmiEventHandler: Mutation tracking set up successfully");
     };
+    /**
+     * Set up query tracking for transaction confirmations
+     * Listens for waitForTransactionReceipt queries to detect CONFIRMED status
+     */
+    WagmiEventHandler.prototype.setupQueryTracking = function () {
+        var _this = this;
+        if (!this.queryClient) {
+            return;
+        }
+        logger.info("WagmiEventHandler: Setting up query tracking");
+        var queryCache = this.queryClient.getQueryCache();
+        var unsubscribe = queryCache.subscribe(function (event) {
+            _this.handleQueryEvent(event);
+        });
+        this.unsubscribers.push(unsubscribe);
+        logger.info("WagmiEventHandler: Query tracking set up successfully");
+    };
+    /**
+     * Handle query cache events (transaction confirmations)
+     */
+    WagmiEventHandler.prototype.handleQueryEvent = function (event) {
+        if (event.type !== "updated") {
+            return;
+        }
+        var query = event.query;
+        var queryKey = query.queryKey;
+        if (!queryKey || queryKey.length === 0) {
+            return;
+        }
+        var queryType = queryKey[0];
+        // Only handle waitForTransactionReceipt queries
+        if (queryType !== "waitForTransactionReceipt") {
+            return;
+        }
+        var state = query.state;
+        // Extract receipt status early to include in deduplication key
+        // This ensures CONFIRMED vs REVERTED outcomes are processed separately
+        var receipt = state.data;
+        var receiptStatus = receipt === null || receipt === void 0 ? void 0 : receipt.status;
+        // Create a unique key for this query state to prevent duplicate processing
+        // Include receipt status to distinguish between CONFIRMED and REVERTED outcomes
+        var queryStateKey = "".concat(query.queryHash, ":").concat(state.status, ":").concat(receiptStatus || "");
+        // Skip if we've already processed this query state
+        if (this.processedQueries.has(queryStateKey)) {
+            logger.debug("WagmiEventHandler: Skipping duplicate query event", {
+                queryType: queryType,
+                queryHash: query.queryHash,
+                status: state.status,
+                receiptStatus: receiptStatus,
+            });
+            return;
+        }
+        // Mark this query state as processed
+        this.processedQueries.add(queryStateKey);
+        logger.debug("WagmiEventHandler: Query event", {
+            queryType: queryType,
+            queryHash: query.queryHash,
+            status: state.status,
+        });
+        // Handle transaction receipt queries
+        this.handleTransactionReceiptQuery(query);
+        // Clean up old processed queries to prevent memory leaks
+        cleanupOldEntries(this.processedQueries);
+    };
+    /**
+     * Handle waitForTransactionReceipt query completion
+     * Emits CONFIRMED or REVERTED transaction status
+     */
+    WagmiEventHandler.prototype.handleTransactionReceiptQuery = function (query) {
+        var _a;
+        if (!this.formo.isAutocaptureEnabled("transaction")) {
+            return;
+        }
+        var state = query.state;
+        var queryKey = query.queryKey;
+        // Only handle successful queries (transaction confirmed on chain)
+        if (state.status !== "success") {
+            return;
+        }
+        // Extract hash and chainId from query key
+        // Query key format: ['waitForTransactionReceipt', { hash, chainId, ... }]
+        var params = queryKey[1];
+        var transactionHash = params === null || params === void 0 ? void 0 : params.hash;
+        var chainId = (params === null || params === void 0 ? void 0 : params.chainId) || this.trackingState.lastChainId;
+        if (!transactionHash) {
+            logger.warn("WagmiEventHandler: Transaction receipt query but no hash found");
+            return;
+        }
+        // Retrieve stored transaction details from BROADCASTED event
+        // Normalize hash to lowercase for consistent lookup
+        var normalizedHash = transactionHash.toLowerCase();
+        var pendingTx = this.pendingTransactions.get(normalizedHash);
+        // Use the original sender address from BROADCASTED event if available,
+        // otherwise fall back to current connected address.
+        // This handles wallet switches between broadcast and confirmation.
+        var address = (pendingTx === null || pendingTx === void 0 ? void 0 : pendingTx.address) || this.trackingState.lastAddress;
+        if (!address) {
+            logger.warn("WagmiEventHandler: Transaction receipt query but no address available");
+            return;
+        }
+        try {
+            // Extract receipt data
+            var receipt = state.data;
+            // Determine transaction status from receipt
+            // receipt.status is 'success' or 'reverted' in viem
+            var txStatus = (receipt === null || receipt === void 0 ? void 0 : receipt.status) === "reverted"
+                ? TransactionStatus.REVERTED
+                : TransactionStatus.CONFIRMED;
+            logger.info("WagmiEventHandler: Tracking transaction confirmation", {
+                status: txStatus,
+                transactionHash: transactionHash,
+                address: address,
+                chainId: chainId,
+                blockNumber: (_a = receipt === null || receipt === void 0 ? void 0 : receipt.blockNumber) === null || _a === void 0 ? void 0 : _a.toString(),
+            });
+            this.formo.transaction(__assign(__assign(__assign(__assign(__assign(__assign({ status: txStatus, chainId: chainId || 0, address: address, transactionHash: transactionHash }, ((pendingTx === null || pendingTx === void 0 ? void 0 : pendingTx.data) && { data: pendingTx.data })), ((pendingTx === null || pendingTx === void 0 ? void 0 : pendingTx.to) && { to: pendingTx.to })), ((pendingTx === null || pendingTx === void 0 ? void 0 : pendingTx.value) && { value: pendingTx.value })), ((pendingTx === null || pendingTx === void 0 ? void 0 : pendingTx.function_name) && { function_name: pendingTx.function_name })), ((pendingTx === null || pendingTx === void 0 ? void 0 : pendingTx.function_args) && { function_args: pendingTx.function_args })), ((pendingTx === null || pendingTx === void 0 ? void 0 : pendingTx.builder_codes) && { builder_codes: pendingTx.builder_codes })), 
+            // Spread function args as additional properties (only colliding keys are prefixed)
+            pendingTx === null || pendingTx === void 0 ? void 0 : pendingTx.safeFunctionArgs);
+            // Clean up the pending transaction after confirmation
+            this.pendingTransactions.delete(normalizedHash);
+        }
+        catch (error) {
+            logger.error("WagmiEventHandler: Error handling transaction receipt query:", error);
+        }
+    };
     /**
      * Handle mutation cache events (signatures, transactions)
      */
@@ -264,14 +436,7 @@ var WagmiEventHandler = /** @class */ (function () {
             this.handleTransactionMutation(mutationType, mutation);
         }
         // Clean up old processed mutations to prevent memory leaks
-        // Keep only recent mutations (max 1000 entries)
-        if (this.processedMutations.size > 1000) {
-            var entries = Array.from(this.processedMutations);
-            // Remove oldest 500 entries
-            for (var i = 0; i < 500; i++) {
-                this.processedMutations.delete(entries[i]);
-            }
-        }
+        cleanupOldEntries(this.processedMutations);
     };
     /**
      * Handle signature mutations (signMessage, signTypedData)
@@ -337,8 +502,15 @@ var WagmiEventHandler = /** @class */ (function () {
         var state = mutation.state;
         var variables = state.variables || {};
         var chainId = this.trackingState.lastChainId || variables.chainId;
-        var address = this.trackingState.lastAddress || variables.account || variables.address;
-        if (!address) {
+        // For sendTransaction, user's address is the 'from'
+        // For writeContract, variables.address is the contract address, not the user
+        // variables.account can be a string address or an Account object with an address property
+        var accountValue = variables.account;
+        var accountAddress = typeof accountValue === "string"
+            ? accountValue
+            : accountValue === null || accountValue === void 0 ? void 0 : accountValue.address;
+        var userAddress = this.trackingState.lastAddress || accountAddress || variables.from;
+        if (!userAddress) {
             logger.warn("WagmiEventHandler: Transaction event but no address available");
             return;
         }
@@ -359,18 +531,62 @@ var WagmiEventHandler = /** @class */ (function () {
             else {
                 return; // Ignore idle state
             }
-            // Extract transaction details from variables
-            var data = variables.data;
-            var to = variables.to || variables.address;
+            // Extract transaction details based on mutation type
+            var data = void 0;
+            var to = void 0;
+            var function_name = void 0;
+            var function_args = void 0;
             var value = (_a = variables.value) === null || _a === void 0 ? void 0 : _a.toString();
-            logger.info("WagmiEventHandler: Tracking transaction event", {
-                status: status_2,
-                mutationType: mutationType,
-                address: address,
-                chainId: chainId,
-                transactionHash: transactionHash,
-            });
-            this.formo.transaction(__assign(__assign(__assign(__assign({ status: status_2, chainId: chainId || 0, address: address }, (data && { data: data })), (to && { to: to })), (value && { value: value })), (transactionHash && { transactionHash: transactionHash })));
+            if (mutationType === "writeContract") {
+                // For writeContract, extract function info and encode data
+                var abi = variables.abi, fnName = variables.functionName, args = variables.args, contractAddress = variables.address, dataSuffix = variables.dataSuffix;
+                to = contractAddress;
+                function_name = fnName;
+                if (abi && fnName) {
+                    // Extract function arguments as a name-value map
+                    function_args = extractFunctionArgs(abi, fnName, args);
+                    // Encode the function data synchronously if viem is available
+                    var encodedData = encodeWriteContractData(abi, fnName, args);
+                    if (encodedData) {
+                        // Include dataSuffix (ERC-8021 builder code) so extractBuilderCodes sees full calldata
+                        data = concatCalldataWithSuffix(encodedData, dataSuffix);
+                        logger.debug("WagmiEventHandler: Encoded writeContract data", data.substring(0, 10));
+                    }
+                }
+            }
+            else {
+                // For sendTransaction, use variables directly
+                // Only data is available, function_name and function_args are not sent
+                data = variables.data;
+                to = variables.to;
+            }
+            // Extract builder codes from transaction data (ERC-8021)
+            var builder_codes = extractBuilderCodes(data);
+            logger.info("WagmiEventHandler: Tracking transaction event", __assign({ status: status_2, mutationType: mutationType, address: userAddress, chainId: chainId, transactionHash: transactionHash, function_name: function_name }, (builder_codes && { builder_codes: builder_codes })));
+            // Build safeFunctionArgs with collision handling and struct flattening
+            var safeFunctionArgs = buildSafeFunctionArgs(function_args, RESERVED_FIELDS);
+            // Store transaction details for BROADCASTED status to use in CONFIRMED/REVERTED
+            // Normalize hash to lowercase for consistent lookup
+            // Include the sender address to handle wallet switches between broadcast and confirmation
+            if (status_2 === TransactionStatus.BROADCASTED && transactionHash) {
+                var normalizedHash = transactionHash.toLowerCase();
+                var txDetails = __assign(__assign(__assign(__assign(__assign(__assign(__assign({ address: userAddress }, (data && { data: data })), (to && { to: to })), (value && { value: value })), (function_name && { function_name: function_name })), (function_args && { function_args: function_args })), (builder_codes && { builder_codes: builder_codes })), (safeFunctionArgs && { safeFunctionArgs: safeFunctionArgs }));
+                this.pendingTransactions.set(normalizedHash, txDetails);
+                logger.debug("WagmiEventHandler: Stored pending transaction for confirmation", {
+                    transactionHash: normalizedHash,
+                });
+                // Clean up old pending transactions to prevent memory leaks (keep max 100)
+                // Remove oldest 50 entries when limit exceeded to handle high-throughput scenarios
+                if (this.pendingTransactions.size > 100) {
+                    var keys = Array.from(this.pendingTransactions.keys());
+                    for (var i = 0; i < 50 && i < keys.length; i++) {
+                        this.pendingTransactions.delete(keys[i]);
+                    }
+                }
+            }
+            this.formo.transaction(__assign(__assign(__assign(__assign(__assign(__assign(__assign({ status: status_2, chainId: chainId || 0, address: userAddress }, (data && { data: data })), (to && { to: to })), (value && { value: value })), (transactionHash && { transactionHash: transactionHash })), (function_name && { function_name: function_name })), (function_args && { function_args: function_args })), (builder_codes && { builder_codes: builder_codes })), 
+            // Spread function args as additional properties (only colliding keys are prefixed)
+            safeFunctionArgs);
         }
         catch (error) {
             logger.error("WagmiEventHandler: Error handling transaction mutation:", error);
@@ -426,7 +642,7 @@ var WagmiEventHandler = /** @class */ (function () {
      * Clean up all subscriptions
      */
     WagmiEventHandler.prototype.cleanup = function () {
-        logger.info("WagmiEventHandler: Cleaning up subscriptions");
+        logger.debug("WagmiEventHandler: Cleaning up subscriptions");
         for (var _i = 0, _a = this.unsubscribers; _i < _a.length; _i++) {
             var unsubscribe = _a[_i];
             try {
@@ -438,7 +654,9 @@ var WagmiEventHandler = /** @class */ (function () {
         }
         this.unsubscribers = [];
         this.processedMutations.clear();
-        logger.info("WagmiEventHandler: Cleanup complete");
+        this.processedQueries.clear();
+        this.pendingTransactions.clear();
+        logger.debug("WagmiEventHandler: Cleanup complete");
     };
     return WagmiEventHandler;
 }());

package/dist/esm/src/wagmi/types.d.ts

@@ -89,11 +89,42 @@ export interface MutationCacheEvent {
 export interface MutationCache {
     subscribe(listener: (event: MutationCacheEvent) => void): () => void;
 }
+/**
+ * React Query query state
+ */
+export interface QueryState {
+    status: 'pending' | 'success' | 'error';
+    data?: any;
+    error?: Error | null;
+    fetchStatus: 'fetching' | 'paused' | 'idle';
+}
+/**
+ * React Query query object
+ */
+export interface Query {
+    state: QueryState;
+    queryKey: readonly unknown[];
+    queryHash: string;
+}
+/**
+ * React Query query cache event
+ */
+export interface QueryCacheEvent {
+    type: 'added' | 'removed' | 'updated';
+    query: Query;
+}
+/**
+ * React Query QueryCache interface
+ */
+export interface QueryCache {
+    subscribe(listener: (event: QueryCacheEvent) => void): () => void;
+}
 /**
  * React Query QueryClient interface
  */
 export interface QueryClient {
     getMutationCache(): MutationCache;
+    getQueryCache(): QueryCache;
 }
 /**
  * Unsubscribe function returned by subscriptions

package/dist/esm/src/wagmi/utils.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Utility functions for Wagmi event handling
+ *
+ * Provides ABI encoding utilities for extracting transaction data from
+ * writeContract mutations without requiring viem as a direct dependency.
+ */
+/**
+ * Flatten a nested object into a flat object with underscore-separated keys.
+ * Only leaf values (primitives) are included; intermediate objects are not.
+ *
+ * Example:
+ *   Input: { o: { x: "100", inner: { a: "42", b: "0xRecipient" } } }
+ *   Output: { o_x: "100", o_inner_a: "42", o_inner_b: "0xRecipient" }
+ *
+ * @param obj - The object to flatten
+ * @param prefix - Optional prefix for keys (used in recursion)
+ * @returns A flat object with underscore-separated keys
+ */
+export declare function flattenObject(obj: Record<string, unknown>, prefix?: string): Record<string, unknown>;
+/**
+ * ABI function item type
+ */
+export interface AbiItem {
+    type: string;
+    name?: string;
+    inputs?: AbiInput[];
+    outputs?: AbiOutput[];
+    stateMutability?: string;
+}
+export interface AbiInput {
+    name: string;
+    type: string;
+    indexed?: boolean;
+    components?: AbiInput[];
+    internalType?: string;
+}
+export interface AbiOutput {
+    name: string;
+    type: string;
+    components?: AbiOutput[];
+    internalType?: string;
+}
+/**
+ * Concatenate encoded calldata with an optional ERC-8021 dataSuffix (e.g. builder codes).
+ * Uses viem's concatHex when available for correct hex handling.
+ */
+export declare function concatCalldataWithSuffix(encodedData: string, dataSuffix: string | undefined): string;
+/**
+ * Encode writeContract data using viem's encodeFunctionData
+ *
+ * @param abi - The contract ABI
+ * @param functionName - The function name to encode
+ * @param args - The function arguments
+ * @returns The encoded calldata or undefined if encoding fails
+ */
+export declare function encodeWriteContractData(abi: AbiItem[], functionName: string, args?: unknown[]): string | undefined;
+/**
+ * Extract function arguments as a name-value map from ABI and args array
+ *
+ * @param abi - The contract ABI
+ * @param functionName - The function name
+ * @param args - The function arguments array
+ * @returns A map of argument names to values, or undefined if extraction fails
+ */
+export declare function extractFunctionArgs(abi: AbiItem[], functionName: string, args?: unknown[]): Record<string, unknown> | undefined;
+/**
+ * Build safe function args with collision handling and struct flattening.
+ *
+ * This function:
+ * 1. Prefixes top-level args that collide with reserved fields (e.g., 'to' -> 'arg_to')
+ * 2. Flattens nested struct values for easier querying (e.g., order.maker -> order_maker)
+ * 3. Skips flattened keys that would collide with existing top-level args
+ *
+ * @param functionArgs - The extracted function arguments
+ * @param reservedFields - Set of reserved field names that need prefixing
+ * @returns Safe function args object, or undefined if input is undefined
+ */
+export declare function buildSafeFunctionArgs(functionArgs: Record<string, unknown> | undefined, reservedFields: Set<string>): Record<string, unknown> | undefined;
+//# sourceMappingURL=utils.d.ts.map

package/dist/esm/src/wagmi/utils.js

@@ -0,0 +1,211 @@
+/**
+ * Utility functions for Wagmi event handling
+ *
+ * Provides ABI encoding utilities for extracting transaction data from
+ * writeContract mutations without requiring viem as a direct dependency.
+ */
+import { logger } from "../logger";
+/**
+ * Flatten a nested object into a flat object with underscore-separated keys.
+ * Only leaf values (primitives) are included; intermediate objects are not.
+ *
+ * Example:
+ *   Input: { o: { x: "100", inner: { a: "42", b: "0xRecipient" } } }
+ *   Output: { o_x: "100", o_inner_a: "42", o_inner_b: "0xRecipient" }
+ *
+ * @param obj - The object to flatten
+ * @param prefix - Optional prefix for keys (used in recursion)
+ * @returns A flat object with underscore-separated keys
+ */
+export function flattenObject(obj, prefix) {
+    if (prefix === void 0) { prefix = ""; }
+    var result = {};
+    for (var _i = 0, _a = Object.entries(obj); _i < _a.length; _i++) {
+        var _b = _a[_i], key = _b[0], value = _b[1];
+        var newKey = prefix ? "".concat(prefix, "_").concat(key) : key;
+        if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+            // Recursively flatten nested objects
+            var nested = flattenObject(value, newKey);
+            Object.assign(result, nested);
+        }
+        else {
+            // Leaf value (primitive or array) - add directly
+            result[newKey] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Recursively convert all BigInt values to strings for JSON serialization
+ * Handles nested objects, arrays, and deeply nested structures (e.g., Solidity structs)
+ *
+ * @param value - The value to convert
+ * @returns The value with all BigInt converted to strings
+ */
+function convertBigIntToString(value) {
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    if (Array.isArray(value)) {
+        return value.map(convertBigIntToString);
+    }
+    if (value !== null && typeof value === "object") {
+        var result = {};
+        for (var _i = 0, _a = Object.entries(value); _i < _a.length; _i++) {
+            var _b = _a[_i], key = _b[0], val = _b[1];
+            result[key] = convertBigIntToString(val);
+        }
+        return result;
+    }
+    return value;
+}
+// Cached viem module reference
+var viemModule;
+/**
+ * Try to load viem synchronously via require
+ * Returns null if viem is not available
+ */
+function tryLoadViem() {
+    if (viemModule !== undefined) {
+        return viemModule;
+    }
+    try {
+        // Use require to load viem synchronously
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        var viem = require("viem");
+        if (viem === null || viem === void 0 ? void 0 : viem.encodeFunctionData) {
+            viemModule = {
+                encodeFunctionData: viem.encodeFunctionData,
+                concatHex: viem.concatHex,
+            };
+            return viemModule;
+        }
+    }
+    catch (_a) {
+        // viem is not available
+    }
+    viemModule = null;
+    return null;
+}
+/**
+ * Concatenate encoded calldata with an optional ERC-8021 dataSuffix (e.g. builder codes).
+ * Uses viem's concatHex when available for correct hex handling.
+ */
+export function concatCalldataWithSuffix(encodedData, dataSuffix) {
+    if (!dataSuffix || dataSuffix === "0x") {
+        return encodedData;
+    }
+    var viem = tryLoadViem();
+    if (viem === null || viem === void 0 ? void 0 : viem.concatHex) {
+        return viem.concatHex([
+            encodedData,
+            dataSuffix,
+        ]);
+    }
+    var suffixHex = dataSuffix.replace(/^0x/i, "");
+    return "".concat(encodedData).concat(suffixHex);
+}
+/**
+ * Encode writeContract data using viem's encodeFunctionData
+ *
+ * @param abi - The contract ABI
+ * @param functionName - The function name to encode
+ * @param args - The function arguments
+ * @returns The encoded calldata or undefined if encoding fails
+ */
+export function encodeWriteContractData(abi, functionName, args) {
+    try {
+        var viem = tryLoadViem();
+        if (!viem) {
+            logger.debug("WagmiEventHandler: viem not available, cannot encode function data");
+            return undefined;
+        }
+        var data = viem.encodeFunctionData({
+            abi: abi,
+            functionName: functionName,
+            args: args || [],
+        });
+        return data;
+    }
+    catch (error) {
+        logger.warn("WagmiEventHandler: Failed to encode function data", error);
+        return undefined;
+    }
+}
+/**
+ * Extract function arguments as a name-value map from ABI and args array
+ *
+ * @param abi - The contract ABI
+ * @param functionName - The function name
+ * @param args - The function arguments array
+ * @returns A map of argument names to values, or undefined if extraction fails
+ */
+export function extractFunctionArgs(abi, functionName, args) {
+    if (!abi || !functionName || !args || !Array.isArray(args)) {
+        return undefined;
+    }
+    try {
+        // Find the function in the ABI
+        var abiItem = abi.find(function (item) { return item.type === "function" && item.name === functionName; });
+        if (!(abiItem === null || abiItem === void 0 ? void 0 : abiItem.inputs) || !Array.isArray(abiItem.inputs)) {
+            return undefined;
+        }
+        var result_1 = {};
+        abiItem.inputs.forEach(function (input, index) {
+            if (index < args.length) {
+                var argValue = args[index];
+                var argName = input.name || "arg".concat(index);
+                // Recursively convert BigInt to string for JSON serialization
+                // Handles: direct BigInt, arrays with BigInt, nested objects/structs with BigInt
+                result_1[argName] = convertBigIntToString(argValue);
+            }
+        });
+        return result_1;
+    }
+    catch (error) {
+        logger.warn("WagmiEventHandler: Failed to extract function args", error);
+        return undefined;
+    }
+}
+/**
+ * Build safe function args with collision handling and struct flattening.
+ *
+ * This function:
+ * 1. Prefixes top-level args that collide with reserved fields (e.g., 'to' -> 'arg_to')
+ * 2. Flattens nested struct values for easier querying (e.g., order.maker -> order_maker)
+ * 3. Skips flattened keys that would collide with existing top-level args
+ *
+ * @param functionArgs - The extracted function arguments
+ * @param reservedFields - Set of reserved field names that need prefixing
+ * @returns Safe function args object, or undefined if input is undefined
+ */
+export function buildSafeFunctionArgs(functionArgs, reservedFields) {
+    if (!functionArgs) {
+        return undefined;
+    }
+    var result = {};
+    for (var _i = 0, _a = Object.entries(functionArgs); _i < _a.length; _i++) {
+        var _b = _a[_i], key = _b[0], val = _b[1];
+        var safeKey = reservedFields.has(key) ? "arg_".concat(key) : key;
+        result[safeKey] = val;
+        // If the value is a nested object (struct), flatten it
+        // Skip flattened keys that would overwrite existing top-level args
+        if (val !== null && typeof val === "object" && !Array.isArray(val)) {
+            var flattened = flattenObject(val, safeKey);
+            for (var _c = 0, _d = Object.entries(flattened); _c < _d.length; _c++) {
+                var _e = _d[_c], flatKey = _e[0], flatVal = _e[1];
+                if (!(flatKey in result)) {
+                    result[flatKey] = flatVal;
+                }
+                else {
+                    logger.debug("WagmiEventHandler: Skipping flattened key collision", {
+                        flatKey: flatKey,
+                        existingValue: result[flatKey],
+                    });
+                }
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=utils.js.map