@formo/analytics 1.27.0 → 1.28.0

package/dist/esm/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/esm/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/esm/src/utils/address.js

@@ -3,6 +3,8 @@ import { utf8ToBytes } from "ethereum-cryptography/utils.js";
 import { ensureIfUint8Array, isAddress, uint8ArrayToHexString, } from "../validators";
 import { isNullish } from "../validators/object";
 import { BLOCKED_ADDRESSES } from "../constants";
+import { isSolanaAddress, getValidSolanaAddress } from "../solana/address";
+import { SOLANA_CHAIN_IDS } from "../solana/types";
 /**
  * Private helper function to validate and trim an address
  * @param address The address to validate and trim
@@ -78,4 +80,47 @@ export var toChecksumAddress = function (address) {
     }
     return checksumAddress;
 };
+/**
+ * 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 var validateAndChecksumAddress = function (address) {
+    var validAddress = getValidAddress(address);
+    return validAddress ? toChecksumAddress(validAddress) : 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 var validateAddress = function (address, chainId) {
+    var solanaChainIds = Object.values(SOLANA_CHAIN_IDS);
+    // Explicit Solana chainId → validate ONLY as Solana
+    if (chainId !== undefined && chainId !== null && solanaChainIds.includes(chainId)) {
+        return getValidSolanaAddress(address) || undefined;
+    }
+    // Explicit non-Solana chainId → validate ONLY as EVM
+    if (chainId !== undefined && chainId !== null) {
+        return validateAndChecksumAddress(address);
+    }
+    // No chainId → try EVM first, then Solana fallback
+    var validEvmAddress = validateAndChecksumAddress(address);
+    if (validEvmAddress) {
+        return validEvmAddress;
+    }
+    if (isSolanaAddress(address)) {
+        return getValidSolanaAddress(address) || undefined;
+    }
+    return undefined;
+};
 //# sourceMappingURL=address.js.map

package/dist/esm/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/esm/src/utils/builderCode.js

@@ -0,0 +1,140 @@
+/**
+ * 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/
+ */
+/** 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
+ */
+export 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/esm/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/esm/src/utils/index.js

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

package/dist/esm/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/esm/src/version.js

@@ -1,4 +1,4 @@
 // This file is auto-generated by scripts/update-version.js during npm version
 // Do not edit manually - it will be overwritten
-export var version = '1.27.0';
+export var version = '1.28.0';
 //# sourceMappingURL=version.js.map

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

@@ -54,7 +54,8 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
 };
 import { SignatureStatus, TransactionStatus } from "../types/events";
 import { logger } from "../logger";
-import { encodeWriteContractData, extractFunctionArgs, buildSafeFunctionArgs, } from "./utils";
+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.
@@ -69,6 +70,7 @@ var RESERVED_FIELDS = new Set([
     "transactionHash",
     "function_name",
     "function_args",
+    "builder_codes",
 ]);
 /**
  * Clean up old entries from a Set to prevent memory leaks.
@@ -383,7 +385,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
@@ -537,7 +539,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) {
@@ -546,7 +548,8 @@ var WagmiEventHandler = /** @class */ (function () {
                     // Encode the function data synchronously if viem is available
                     var encodedData = encodeWriteContractData(abi, fnName, args);
                     if (encodedData) {
-                        data = 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));
                     }
                 }
@@ -557,14 +560,9 @@ var WagmiEventHandler = /** @class */ (function () {
                 data = variables.data;
                 to = variables.to;
             }
-            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 = 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
@@ -572,7 +570,7 @@ var WagmiEventHandler = /** @class */ (function () {
             // 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({ 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.debug("WagmiEventHandler: Stored pending transaction for confirmation", {
                     transactionHash: normalizedHash,
@@ -586,7 +584,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);
         }
@@ -644,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 {
@@ -658,7 +656,7 @@ var WagmiEventHandler = /** @class */ (function () {
         this.processedMutations.clear();
         this.processedQueries.clear();
         this.pendingTransactions.clear();
-        logger.info("WagmiEventHandler: Cleanup complete");
+        logger.debug("WagmiEventHandler: Cleanup complete");
     };
     return WagmiEventHandler;
 }());

package/dist/esm/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/esm/src/wagmi/utils.js

@@ -76,6 +76,7 @@ function tryLoadViem() {
         if (viem === null || viem === void 0 ? void 0 : viem.encodeFunctionData) {
             viemModule = {
                 encodeFunctionData: viem.encodeFunctionData,
+                concatHex: viem.concatHex,
             };
             return viemModule;
         }
@@ -86,6 +87,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.
+ */
+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
  *