@formo/analytics 1.27.0 → 1.28.0

package/dist/cjs/src/types/base.d.ts

@@ -2,9 +2,18 @@ import { LogLevel } from "../logger";
 import { IFormoEventContext, IFormoEventProperties, SignatureStatus, TransactionStatus } from "./events";
 import { EIP1193Provider } from "./provider";
 import { ReactNode } from "react";
+import { SolanaOptions } from "../solana/types";
 export type Nullable<T> = T | null;
 export type ChainID = number;
 export type Address = string;
+export type ChainNamespace = 'evm' | 'solana';
+export interface ChainState {
+    address?: Address;
+    chainId?: ChainID;
+}
+export interface EvmChainState extends ChainState {
+    provider?: EIP1193Provider;
+}
 export type ValidInputTypes = Uint8Array | bigint | string | number | boolean;
 export interface IFormoAnalytics {
     page(category?: string, name?: string, properties?: IFormoEventProperties, context?: IFormoEventContext, callback?: (...args: unknown[]) => void): Promise<void>;
@@ -151,6 +160,14 @@ export interface Options {
      * @requires @tanstack/react-query@>=5.0.0 (for mutation tracking)
      */
     wagmi?: WagmiOptions;
+    /**
+     * Solana Wallet Adapter integration configuration
+     * When provided, the SDK will track Solana wallet events in addition to EVM wallet events
+     * This works alongside EIP-1193/Wagmi tracking - you can track both EVM and Solana wallets
+     * @requires @solana/wallet-adapter-base (optional peer dependency)
+     * @requires @solana/wallet-adapter-react (optional peer dependency, for React apps)
+     */
+    solana?: SolanaOptions;
     /**
      * Custom API host for sending events through your own domain to bypass ad blockers
      * - If not provided, events are sent directly to events.formo.so

package/dist/cjs/src/types/events.d.ts

@@ -44,9 +44,9 @@ export interface DetectAPIEvent {
 }
 export interface IdentifyAPIEvent {
     type: "identify";
-    address: string;
-    providerName: string;
-    rdns: string;
+    address: Address;
+    providerName?: string;
+    rdns?: string;
     userId?: Nullable<string>;
 }
 export interface ChainAPIEvent {
@@ -65,6 +65,7 @@ export interface TransactionAPIEvent {
     transactionHash?: string;
     function_name?: string;
     function_args?: Record<string, unknown>;
+    builder_codes?: string;
 }
 export interface SignatureAPIEvent {
     type: "signature";

package/dist/cjs/src/utils/address.d.ts

@@ -26,4 +26,25 @@ export declare const getValidAddress: (address: Address | null | undefined) => s
  */
 export declare const isBlockedAddress: (address: Address | null | undefined) => boolean;
 export declare const toChecksumAddress: (address: Address) => string;
+/**
+ * Validates an EVM address and returns it in checksummed format.
+ * @param address The address to validate
+ * @returns The checksummed address or undefined if invalid
+ */
+export declare const validateAndChecksumAddress: (address: string) => Address | undefined;
+/**
+ * Validates an address for both EVM and Solana chains.
+ * For EVM addresses, returns checksummed format.
+ * For Solana addresses, returns the Base58 address as-is.
+ *
+ * When chainId is explicitly provided, validation is strict:
+ * - Solana chainId → only Solana validation
+ * - Non-Solana chainId → only EVM validation
+ * When chainId is omitted, EVM is tried first with Solana fallback.
+ *
+ * @param address The address to validate
+ * @param chainId Optional chain ID to determine address type
+ * @returns The validated address or undefined if invalid
+ */
+export declare const validateAddress: (address: string, chainId?: number) => Address | undefined;
 //# sourceMappingURL=address.d.ts.map

package/dist/cjs/src/utils/address.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toChecksumAddress = exports.isBlockedAddress = exports.getValidAddress = exports.isValidAddress = void 0;
+exports.validateAddress = exports.validateAndChecksumAddress = exports.toChecksumAddress = exports.isBlockedAddress = exports.getValidAddress = exports.isValidAddress = void 0;
 var keccak_js_1 = require("ethereum-cryptography/keccak.js");
 var utils_js_1 = require("ethereum-cryptography/utils.js");
 var validators_1 = require("../validators");
 var object_1 = require("../validators/object");
 var constants_1 = require("../constants");
+var address_1 = require("../solana/address");
+var types_1 = require("../solana/types");
 /**
  * Private helper function to validate and trim an address
  * @param address The address to validate and trim
@@ -85,4 +87,49 @@ var toChecksumAddress = function (address) {
     return checksumAddress;
 };
 exports.toChecksumAddress = toChecksumAddress;
+/**
+ * Validates an EVM address and returns it in checksummed format.
+ * @param address The address to validate
+ * @returns The checksummed address or undefined if invalid
+ */
+var validateAndChecksumAddress = function (address) {
+    var validAddress = (0, exports.getValidAddress)(address);
+    return validAddress ? (0, exports.toChecksumAddress)(validAddress) : undefined;
+};
+exports.validateAndChecksumAddress = validateAndChecksumAddress;
+/**
+ * Validates an address for both EVM and Solana chains.
+ * For EVM addresses, returns checksummed format.
+ * For Solana addresses, returns the Base58 address as-is.
+ *
+ * When chainId is explicitly provided, validation is strict:
+ * - Solana chainId → only Solana validation
+ * - Non-Solana chainId → only EVM validation
+ * When chainId is omitted, EVM is tried first with Solana fallback.
+ *
+ * @param address The address to validate
+ * @param chainId Optional chain ID to determine address type
+ * @returns The validated address or undefined if invalid
+ */
+var validateAddress = function (address, chainId) {
+    var solanaChainIds = Object.values(types_1.SOLANA_CHAIN_IDS);
+    // Explicit Solana chainId → validate ONLY as Solana
+    if (chainId !== undefined && chainId !== null && solanaChainIds.includes(chainId)) {
+        return (0, address_1.getValidSolanaAddress)(address) || undefined;
+    }
+    // Explicit non-Solana chainId → validate ONLY as EVM
+    if (chainId !== undefined && chainId !== null) {
+        return (0, exports.validateAndChecksumAddress)(address);
+    }
+    // No chainId → try EVM first, then Solana fallback
+    var validEvmAddress = (0, exports.validateAndChecksumAddress)(address);
+    if (validEvmAddress) {
+        return validEvmAddress;
+    }
+    if ((0, address_1.isSolanaAddress)(address)) {
+        return (0, address_1.getValidSolanaAddress)(address) || undefined;
+    }
+    return undefined;
+};
+exports.validateAddress = validateAddress;
 //# sourceMappingURL=address.js.map

package/dist/cjs/src/utils/builderCode.d.ts

@@ -0,0 +1,30 @@
+/**
+ * ERC-8021 Builder Code Extraction
+ *
+ * Extracts builder codes from transaction calldata by parsing the ERC-8021
+ * data suffix. The suffix is appended to the end of calldata and parsed
+ * backwards:
+ *
+ *   [original calldata] [schemaData] [schemaId (1 byte)] [ercMarker (16 bytes)]
+ *
+ * Schema 0 (canonical registry):
+ *   [codes (variable ASCII)] [codesLength (1 byte)] [schemaId 0x00] [ercMarker]
+ *
+ * Schema 1 (custom registry):
+ *   [registryAddress (20 bytes)] [chainId (variable)] [chainIdLength (1 byte)]
+ *   [codes (variable ASCII)] [codesLength (1 byte)] [schemaId 0x01] [ercMarker]
+ *
+ * - ercMarker: 0x80218021802180218021802180218021 (16 bytes)
+ * - codes: ASCII-encoded entity codes delimited by 0x2C (comma)
+ *
+ * @see https://docs.base.org/base-chain/builder-codes/builder-codes
+ * @see https://www.erc8021.com/
+ */
+/**
+ * Extract builder codes from transaction calldata by parsing the ERC-8021 suffix.
+ *
+ * @param data - The transaction calldata hex string (with or without 0x prefix)
+ * @returns A comma-separated string of builder codes (e.g. "uniswap,base"), or undefined if no valid ERC-8021 suffix is found
+ */
+export declare function extractBuilderCodes(data: string | undefined | null): string | undefined;
+//# sourceMappingURL=builderCode.d.ts.map

package/dist/cjs/src/utils/builderCode.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * ERC-8021 Builder Code Extraction
+ *
+ * Extracts builder codes from transaction calldata by parsing the ERC-8021
+ * data suffix. The suffix is appended to the end of calldata and parsed
+ * backwards:
+ *
+ *   [original calldata] [schemaData] [schemaId (1 byte)] [ercMarker (16 bytes)]
+ *
+ * Schema 0 (canonical registry):
+ *   [codes (variable ASCII)] [codesLength (1 byte)] [schemaId 0x00] [ercMarker]
+ *
+ * Schema 1 (custom registry):
+ *   [registryAddress (20 bytes)] [chainId (variable)] [chainIdLength (1 byte)]
+ *   [codes (variable ASCII)] [codesLength (1 byte)] [schemaId 0x01] [ercMarker]
+ *
+ * - ercMarker: 0x80218021802180218021802180218021 (16 bytes)
+ * - codes: ASCII-encoded entity codes delimited by 0x2C (comma)
+ *
+ * @see https://docs.base.org/base-chain/builder-codes/builder-codes
+ * @see https://www.erc8021.com/
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractBuilderCodes = extractBuilderCodes;
+/** The 16-byte ERC-8021 marker appended at the very end of calldata */
+var ERC_MARKER = "80218021802180218021802180218021";
+/** Length of the ERC marker in hex characters (16 bytes = 32 hex chars) */
+var ERC_MARKER_HEX_LENGTH = 32;
+/** Supported schema IDs */
+var SCHEMA_ID_CANONICAL = "00";
+var SCHEMA_ID_CUSTOM_REGISTRY = "01";
+/** Comma delimiter (0x2C) used to separate multiple codes */
+var COMMA_BYTE = 0x2c;
+/**
+ * Decode the codes field from a hex string into a comma-separated string.
+ * Validates that all bytes are printable ASCII (0x20–0x7E).
+ *
+ * @param codesHex - Hex string of the codes field
+ * @returns Comma-separated builder codes string, or undefined if invalid
+ */
+function decodeCodes(codesHex) {
+    var bytes = [];
+    for (var i = 0; i < codesHex.length; i += 2) {
+        var byte = parseInt(codesHex.slice(i, i + 2), 16);
+        // Reject NaN (invalid hex), non-printable or non-ASCII bytes
+        if (isNaN(byte) || byte < 0x20 || byte > 0x7e) {
+            return undefined;
+        }
+        bytes.push(byte);
+    }
+    // Split on comma delimiter and decode each code as ASCII
+    var codes = [];
+    var current = [];
+    for (var _i = 0, bytes_1 = bytes; _i < bytes_1.length; _i++) {
+        var byte = bytes_1[_i];
+        if (byte === COMMA_BYTE) {
+            if (current.length > 0) {
+                codes.push(String.fromCharCode.apply(String, current));
+                current = [];
+            }
+        }
+        else {
+            current.push(byte);
+        }
+    }
+    // Push the last code segment
+    if (current.length > 0) {
+        codes.push(String.fromCharCode.apply(String, current));
+    }
+    return codes.length > 0 ? codes.join(",") : undefined;
+}
+/**
+ * Read codesLength and codes from the hex string ending at the given position.
+ *
+ * @param hex - Full hex string (lowercase, no 0x prefix)
+ * @param endPos - Hex char position where codesLength byte ends (i.e. start of schemaId)
+ * @returns Object with decoded codes string and the hex char position where codes start, or undefined
+ */
+function readCodes(hex, endPos) {
+    // Read codesLength (1 byte before endPos)
+    var codesLengthStart = endPos - 2;
+    if (codesLengthStart < 0) {
+        return undefined;
+    }
+    var codesLength = parseInt(hex.slice(codesLengthStart, endPos), 16);
+    if (codesLength === 0 || isNaN(codesLength)) {
+        return undefined;
+    }
+    // Read the codes field
+    var codesHexLength = codesLength * 2;
+    var codesStart = codesLengthStart - codesHexLength;
+    if (codesStart < 0) {
+        return undefined;
+    }
+    var codesHex = hex.slice(codesStart, codesLengthStart);
+    var codes = decodeCodes(codesHex);
+    if (!codes) {
+        return undefined;
+    }
+    return { codes: codes, codesStart: codesStart };
+}
+/**
+ * Extract builder codes from transaction calldata by parsing the ERC-8021 suffix.
+ *
+ * @param data - The transaction calldata hex string (with or without 0x prefix)
+ * @returns A comma-separated string of builder codes (e.g. "uniswap,base"), or undefined if no valid ERC-8021 suffix is found
+ */
+function extractBuilderCodes(data) {
+    if (!data || typeof data !== "string") {
+        return undefined;
+    }
+    // Normalize: remove 0x prefix and work with lowercase hex
+    var hex = data.startsWith("0x") || data.startsWith("0X")
+        ? data.slice(2).toLowerCase()
+        : data.toLowerCase();
+    // Minimum suffix: 1+ byte codes + 1 byte codesLength + 1 byte schemaId + 16 bytes marker = 19 bytes = 38 hex chars
+    if (hex.length < 38) {
+        return undefined;
+    }
+    // Step 1: Check last 16 bytes for ERC marker
+    var markerStart = hex.length - ERC_MARKER_HEX_LENGTH;
+    var marker = hex.slice(markerStart);
+    if (marker !== ERC_MARKER) {
+        return undefined;
+    }
+    // Step 2: Read schemaId (1 byte before the marker)
+    var schemaIdStart = markerStart - 2;
+    if (schemaIdStart < 0) {
+        return undefined;
+    }
+    var schemaId = hex.slice(schemaIdStart, markerStart);
+    // Step 3: Parse based on schemaId
+    if (schemaId === SCHEMA_ID_CANONICAL || schemaId === SCHEMA_ID_CUSTOM_REGISTRY) {
+        // Both Schema 0 and Schema 1 have codes in the same position
+        // (immediately before schemaId when parsing backwards)
+        var result = readCodes(hex, schemaIdStart);
+        return result === null || result === void 0 ? void 0 : result.codes;
+    }
+    // Unknown schema - cannot parse
+    return undefined;
+}
+//# sourceMappingURL=builderCode.js.map

package/dist/cjs/src/utils/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./address";
 export * from "./base";
+export * from "./builderCode";
 export * from "./converter";
 export * from "./generate";
 export * from "./hash";

package/dist/cjs/src/utils/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./address"), exports);
 __exportStar(require("./base"), exports);
+__exportStar(require("./builderCode"), exports);
 __exportStar(require("./converter"), exports);
 __exportStar(require("./generate"), exports);
 __exportStar(require("./hash"), exports);

package/dist/cjs/src/version.d.ts

@@ -1,2 +1,2 @@
-export declare const version = "1.27.0";
+export declare const version = "1.28.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/cjs/src/version.js

@@ -3,5 +3,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.version = void 0;
 // This file is auto-generated by scripts/update-version.js during npm version
 // Do not edit manually - it will be overwritten
-exports.version = '1.27.0';
+exports.version = '1.28.0';
 //# sourceMappingURL=version.js.map

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

@@ -58,6 +58,7 @@ exports.WagmiEventHandler = void 0;
 var events_1 = require("../types/events");
 var logger_1 = require("../logger");
 var utils_1 = require("./utils");
+var builderCode_1 = require("../utils/builderCode");
 /**
  * Built-in transaction fields that could collide with function args.
  * Defined at module level to avoid recreating on every method call.
@@ -72,6 +73,7 @@ var RESERVED_FIELDS = new Set([
     "transactionHash",
     "function_name",
     "function_args",
+    "builder_codes",
 ]);
 /**
  * Clean up old entries from a Set to prevent memory leaks.
@@ -386,7 +388,7 @@ var WagmiEventHandler = /** @class */ (function () {
                 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({ 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 })), 
+            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
@@ -540,7 +542,7 @@ var WagmiEventHandler = /** @class */ (function () {
             var value = (_a = variables.value) === null || _a === void 0 ? void 0 : _a.toString();
             if (mutationType === "writeContract") {
                 // For writeContract, extract function info and encode data
-                var abi = variables.abi, fnName = variables.functionName, args = variables.args, contractAddress = variables.address;
+                var abi = variables.abi, fnName = variables.functionName, args = variables.args, contractAddress = variables.address, dataSuffix = variables.dataSuffix;
                 to = contractAddress;
                 function_name = fnName;
                 if (abi && fnName) {
@@ -549,7 +551,8 @@ var WagmiEventHandler = /** @class */ (function () {
                     // Encode the function data synchronously if viem is available
                     var encodedData = (0, utils_1.encodeWriteContractData)(abi, fnName, args);
                     if (encodedData) {
-                        data = encodedData;
+                        // Include dataSuffix (ERC-8021 builder code) so extractBuilderCodes sees full calldata
+                        data = (0, utils_1.concatCalldataWithSuffix)(encodedData, dataSuffix);
                         logger_1.logger.debug("WagmiEventHandler: Encoded writeContract data", data.substring(0, 10));
                     }
                 }
@@ -560,14 +563,9 @@ var WagmiEventHandler = /** @class */ (function () {
                 data = variables.data;
                 to = variables.to;
             }
-            logger_1.logger.info("WagmiEventHandler: Tracking transaction event", {
-                status: status_2,
-                mutationType: mutationType,
-                address: userAddress,
-                chainId: chainId,
-                transactionHash: transactionHash,
-                function_name: function_name,
-            });
+            // Extract builder codes from transaction data (ERC-8021)
+            var builder_codes = (0, builderCode_1.extractBuilderCodes)(data);
+            logger_1.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 = (0, utils_1.buildSafeFunctionArgs)(function_args, RESERVED_FIELDS);
             // Store transaction details for BROADCASTED status to use in CONFIRMED/REVERTED
@@ -575,7 +573,7 @@ var WagmiEventHandler = /** @class */ (function () {
             // Include the sender address to handle wallet switches between broadcast and confirmation
             if (status_2 === events_1.TransactionStatus.BROADCASTED && transactionHash) {
                 var normalizedHash = transactionHash.toLowerCase();
-                var txDetails = __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 })), (safeFunctionArgs && { safeFunctionArgs: safeFunctionArgs }));
+                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_1.logger.debug("WagmiEventHandler: Stored pending transaction for confirmation", {
                     transactionHash: normalizedHash,
@@ -589,7 +587,7 @@ var WagmiEventHandler = /** @class */ (function () {
                     }
                 }
             }
-            this.formo.transaction(__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 })), 
+            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);
         }
@@ -647,7 +645,7 @@ var WagmiEventHandler = /** @class */ (function () {
      * Clean up all subscriptions
      */
     WagmiEventHandler.prototype.cleanup = function () {
-        logger_1.logger.info("WagmiEventHandler: Cleaning up subscriptions");
+        logger_1.logger.debug("WagmiEventHandler: Cleaning up subscriptions");
         for (var _i = 0, _a = this.unsubscribers; _i < _a.length; _i++) {
             var unsubscribe = _a[_i];
             try {
@@ -661,7 +659,7 @@ var WagmiEventHandler = /** @class */ (function () {
         this.processedMutations.clear();
         this.processedQueries.clear();
         this.pendingTransactions.clear();
-        logger_1.logger.info("WagmiEventHandler: Cleanup complete");
+        logger_1.logger.debug("WagmiEventHandler: Cleanup complete");
     };
     return WagmiEventHandler;
 }());

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

@@ -40,6 +40,11 @@ export interface AbiOutput {
     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
  *

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

@@ -7,6 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.flattenObject = flattenObject;
+exports.concatCalldataWithSuffix = concatCalldataWithSuffix;
 exports.encodeWriteContractData = encodeWriteContractData;
 exports.extractFunctionArgs = extractFunctionArgs;
 exports.buildSafeFunctionArgs = buildSafeFunctionArgs;
@@ -82,6 +83,7 @@ function tryLoadViem() {
         if (viem === null || viem === void 0 ? void 0 : viem.encodeFunctionData) {
             viemModule = {
                 encodeFunctionData: viem.encodeFunctionData,
+                concatHex: viem.concatHex,
             };
             return viemModule;
         }
@@ -92,6 +94,24 @@ function tryLoadViem() {
     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.
+ */
+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
  *

package/dist/esm/src/FormoAnalytics.d.ts

@@ -1,9 +1,15 @@
 import { EIP6963ProviderDetail } from "mipd";
 import { Address, ChainID, Config, EIP1193Provider, IFormoAnalytics, IFormoEventContext, IFormoEventProperties, Options, SignatureStatus, TransactionStatus } from "./types";
+import { SolanaManager } from "./solana/SolanaManager";
 export declare class FormoAnalytics implements IFormoAnalytics {
     readonly writeKey: string;
     options: Options;
-    private _provider?;
+    private _chainState;
+    private _activeNamespace?;
+    private get _provider();
+    private set _provider(value);
+    private get _evmAddress();
+    private get _evmChainId();
     private _providerListenersMap;
     private session;
     private eventManager;
@@ -29,6 +35,11 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * Only initialized when options.wagmi is provided
      */
     private wagmiHandler?;
+    /**
+     * Solana integration manager for tracking Solana wallet events.
+     * Only initialized when options.solana is provided or via formo.solana.
+     */
+    private solanaManager?;
     /**
      * Flag indicating if Wagmi mode is enabled
      * When true, EIP-1193 provider wrapping is skipped
@@ -139,7 +150,7 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * @param {(...args: unknown[]) => void} callback
      * @returns {Promise<void>}
      */
-    transaction({ status, chainId, address, data, to, value, transactionHash, function_name, function_args, }: {
+    transaction({ status, chainId, address, data, to, value, transactionHash, function_name, function_args, builder_codes, }: {
         status: TransactionStatus;
         chainId: ChainID;
         address: Address;
@@ -149,20 +160,38 @@ export declare class FormoAnalytics implements IFormoAnalytics {
         transactionHash?: string;
         function_name?: string;
         function_args?: Record<string, unknown>;
+        builder_codes?: string;
     }, properties?: IFormoEventProperties, context?: IFormoEventContext, callback?: (...args: unknown[]) => void): Promise<void>;
     /**
      * Emits an identify event with current wallet address and provider info.
-     * @param {string} params.address
-     * @param {string} params.userId
-     * @param {string} params.rdns
-     * @param {string} params.providerName
-     * @param {IFormoEventProperties} properties
+     *
+     * @param {string} params.address - Wallet address
+     * @param {string} params.userId - External user ID
+     * @param {string} params.rdns - Provider reverse domain name
+     * @param {string} params.providerName - Provider display name
+     * @param {IFormoEventProperties} properties - Additional properties to include with the identify event
      * @param {IFormoEventContext} context
      * @param {(...args: unknown[]) => void} callback
      * @returns {Promise<void>}
+     *
+     * @example
+     * ```ts
+     * // Basic identify
+     * formo.identify({ address: '0x...', userId: 'user123' });
+     *
+     * // With Privy user
+     * import { parsePrivyProperties } from '@formo/analytics';
+     * const { user } = usePrivy();
+     * if (user) {
+     *   const { properties, wallets } = parsePrivyProperties(user);
+     *   for (const wallet of wallets) {
+     *     formo.identify({ address: wallet.address, userId: user.id }, properties);
+     *   }
+     * }
+     * ```
      */
     identify(params?: {
-        address?: Address;
+        address: Address;
         providerName?: string;
         userId?: string;
         rdns?: string;
@@ -258,6 +287,19 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     get providers(): readonly EIP6963ProviderDetail[];
     private detectWallets;
     get provider(): EIP1193Provider | undefined;
+    /**
+     * Access the Solana integration manager.
+     * Lazily creates one if not already initialized.
+     *
+     * @example
+     * ```tsx
+     * formo.solana.setWallet(wallet);
+     * formo.solana.setConnection(connection);
+     * formo.solana.setCluster("devnet");
+     * formo.solana.syncWalletState();
+     * ```
+     */
+    get solana(): SolanaManager;
     private getAddress;
     private getAccounts;
     private getCurrentChainId;
@@ -298,11 +340,26 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      */
     private handleProviderMismatch;
     /**
-     * Helper method to validate and checksum an address
-     * @param address The address to validate and checksum
-     * @returns The checksummed address or undefined if invalid
+     * Determine which namespace a chainId belongs to.
+     */
+    private getNamespace;
+    /**
+     * Update per-chain state and sync the derived currentAddress/currentChainId.
+     * Accepts either a namespace string ('evm'/'solana') or a chainId number
+     * to resolve the namespace automatically. When a chainId number is passed,
+     * it is also stored as the namespace's chainId (unless explicitly overridden
+     * in the update object).
+     */
+    private setChainState;
+    /**
+     * Clear per-chain state for a given namespace (or chainId) and sync derived state.
+     */
+    private clearChainState;
+    /**
+     * Synchronize currentAddress/currentChainId from the active namespace.
+     * Last-connected-chain-wins: _activeNamespace takes precedence.
      */
-    private validateAndChecksumAddress;
+    private syncDerivedState;
     /**
      * Helper method to clear the active provider state
      * Centralizes provider clearing logic for consistency