@beclab/olaresid 0.1.1 → 0.1.2

package/dist/utils/error-parser.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * Contract Error Parser Utility
+ *
+ * This module provides utilities for parsing contract errors from ethers.js
+ * and converting them into user-friendly error messages.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseContractError = parseContractError;
+/**
+ * Complete error selector mapping for all contracts (TerminusDID, RootResolver, RootTagger2, TagRegistry)
+ */
+const ERROR_SELECTORS = {
+    // TerminusDID contract errors
+    '0x89c62b64': 'ERC721InvalidOwner',
+    '0x7e273289': 'ERC721NonexistentToken',
+    '0x64283d7b': 'ERC721IncorrectOwner',
+    '0x73c6ac6e': 'ERC721InvalidSender',
+    '0x64a0ae92': 'ERC721InvalidReceiver',
+    '0x177e802f': 'ERC721InsufficientApproval',
+    '0xa9fbf51f': 'ERC721InvalidApprover',
+    '0x5b08ba18': 'ERC721InvalidOperator',
+    '0x6db122af': 'DomainNotExist',
+    '0x27e1f1e5': 'OnlyOperator',
+    '0xfb5c3755': 'InvalidDomain',
+    '0xc668cf69': 'SubdomainNotAllowed',
+    // RootTagger2 contract errors
+    '0xa3114200': 'RootTagNoExists',
+    '0xe7c4886e': 'AddressNoExists',
+    '0xca7dc5c3': 'AddressHasExisted',
+    '0x390642d4': 'SignatureIsValidOnlyInOneHour',
+    '0x9cc5a685': 'InvalidAddressSignature',
+    '0x871a1000': 'InvalidSolanaAddressSignature',
+    // RootResolver contract errors
+    '0x4a7f394f': 'InvalidAction',
+    '0xfde625f6': 'TagNotExist',
+    '0x4bdbac1b': 'InvalidBytes',
+    // TagRegistry contract errors
+    '0x651e7ee4': 'UndefinedTag',
+    '0x7417940b': 'RedefinedTag',
+    '0x1f7fe073': 'InvalidTagDefinition',
+    '0xc2d32a00': 'TagInvalidOp',
+    '0xe3f3bb98': 'TagTypeIncompatible',
+    '0xa6df187b': 'IncompatibleArrayLengthsForEncode',
+    '0xb62b06eb': 'TagTooManyEntries',
+    // ABI utility errors
+    '0x63df8171': 'InvalidIndex',
+    '0x93c19f61': 'InvalidOp',
+    '0xb9688461': 'InvalidType',
+    '0xaa7feadc': 'InvalidValue',
+    // Common errors
+    '0x82b42900': 'Unauthorized'
+};
+/**
+ * Network error codes that indicate connectivity issues
+ */
+const NETWORK_ERROR_CODES = [
+    'NETWORK_ERROR',
+    'TIMEOUT',
+    'SERVER_ERROR',
+    'ETIMEDOUT',
+    'ECONNREFUSED',
+    'ENOTFOUND'
+];
+/**
+ * Parse contract error and determine if it's a network error or contract error
+ * @param error - The error object from ethers.js
+ * @returns Parsed error information with friendly message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await contract.someFunction();
+ * } catch (error) {
+ *   const parsed = parseContractError(error);
+ *   if (parsed.isNetworkError) {
+ *     throw new Error(`Network error: ${parsed.message}`);
+ *   }
+ *   console.log(parsed.message); // User-friendly message
+ * }
+ * ```
+ */
+function parseContractError(error) {
+    const errorCode = error.code || '';
+    const errorMessage = error.message || String(error);
+    // Check if it's a network error
+    const isNetworkError = NETWORK_ERROR_CODES.some((code) => errorCode.includes(code) || errorMessage.includes(code));
+    let errorName;
+    let errorArgs;
+    // Check for revert with custom error
+    if (error.data && typeof error.data === 'string') {
+        try {
+            const errorSelector = error.data.slice(0, 10);
+            errorName = ERROR_SELECTORS[errorSelector];
+        }
+        catch (e) {
+            // Ignore parsing errors
+        }
+    }
+    // Check error message for known patterns (fallback)
+    if (!errorName && errorMessage) {
+        Object.values(ERROR_SELECTORS).forEach((name) => {
+            if (errorMessage.includes(name)) {
+                errorName = name;
+            }
+        });
+    }
+    // Build friendly error message
+    const friendlyMessage = errorName
+        ? getFriendlyErrorMessage(errorName)
+        : errorMessage;
+    return {
+        message: friendlyMessage,
+        isNetworkError,
+        errorName,
+        errorArgs
+    };
+}
+/**
+ * Get user-friendly error message for a given error name
+ * @param errorName - The contract error name
+ * @returns User-friendly error message
+ */
+function getFriendlyErrorMessage(errorName) {
+    switch (errorName) {
+        // RootTagger2 errors
+        case 'RootTagNoExists':
+            return `Tag does not exist for this domain`;
+        case 'AddressNoExists':
+            return `Wallet address does not exist`;
+        case 'AddressHasExisted':
+            return `This wallet address has already been added to the domain`;
+        case 'SignatureIsValidOnlyInOneHour':
+            return `Signature expired: Signatures are only valid for 1 hour`;
+        case 'InvalidAddressSignature':
+            return `Invalid signature: The wallet signature verification failed`;
+        case 'InvalidSolanaAddressSignature':
+            return `Invalid Solana signature: The wallet signature verification failed`;
+        // TerminusDID errors
+        case 'ERC721InvalidOwner':
+            return `Invalid owner address`;
+        case 'ERC721NonexistentToken':
+            return `Domain does not exist`;
+        case 'ERC721IncorrectOwner':
+            return `Incorrect owner: You are not the owner of this domain`;
+        case 'ERC721InvalidSender':
+            return `Invalid sender address`;
+        case 'ERC721InvalidReceiver':
+            return `Invalid receiver address`;
+        case 'ERC721InsufficientApproval':
+            return `Insufficient approval: Caller is not approved to operate this domain`;
+        case 'ERC721InvalidApprover':
+            return `Invalid approver address`;
+        case 'ERC721InvalidOperator':
+            return `Invalid operator address`;
+        case 'DomainNotExist':
+            return `Domain does not exist`;
+        case 'OnlyOperator':
+            return `Only operator can perform this action`;
+        case 'InvalidDomain':
+            return `Invalid domain name format`;
+        case 'SubdomainNotAllowed':
+            return `Subdomain creation is not allowed for this domain`;
+        // RootResolver errors
+        case 'InvalidAction':
+            return `Invalid action`;
+        case 'TagNotExist':
+            return `Tag does not exist`;
+        case 'InvalidBytes':
+            return `Invalid bytes data format`;
+        // TagRegistry errors
+        case 'UndefinedTag':
+            return `Tag is not defined: You must define the tag type before using it`;
+        case 'RedefinedTag':
+            return `Tag already exists: This tag has already been defined for this domain`;
+        case 'InvalidTagDefinition':
+            return `Invalid tag definition: The tag type definition is malformed`;
+        case 'TagInvalidOp':
+            return `Invalid tag operation: The operation is not supported for this tag type or state`;
+        case 'TagTypeIncompatible':
+            return `Tag type mismatch: The value type does not match the defined tag type`;
+        case 'IncompatibleArrayLengthsForEncode':
+            return `Array encoding error: Mismatched array lengths during encoding`;
+        case 'TagTooManyEntries':
+            return `Too many tag entries: The maximum number of tags has been reached`;
+        // ABI utility errors
+        case 'InvalidIndex':
+            return `Invalid array index: The index is out of bounds`;
+        case 'InvalidOp':
+            return `Invalid ABI operation: The operation is not supported for this type`;
+        case 'InvalidType':
+            return `Invalid ABI type: The type definition is malformed`;
+        case 'InvalidValue':
+            return `Invalid value: The value cannot be encoded with the specified type`;
+        // Common errors
+        case 'Unauthorized':
+            return `Unauthorized: You do not have permission to perform this action`;
+        default:
+            return `Contract error: ${errorName}`;
+    }
+}
+//# sourceMappingURL=error-parser.js.map

package/dist/utils/error-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-parser.js","sourceRoot":"","sources":["../../src/utils/error-parser.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAuFH,gDA0CC;AArHD;;GAEG;AACH,MAAM,eAAe,GAA8B;IAClD,8BAA8B;IAC9B,YAAY,EAAE,oBAAoB;IAClC,YAAY,EAAE,wBAAwB;IACtC,YAAY,EAAE,sBAAsB;IACpC,YAAY,EAAE,qBAAqB;IACnC,YAAY,EAAE,uBAAuB;IACrC,YAAY,EAAE,4BAA4B;IAC1C,YAAY,EAAE,uBAAuB;IACrC,YAAY,EAAE,uBAAuB;IACrC,YAAY,EAAE,gBAAgB;IAC9B,YAAY,EAAE,cAAc;IAC5B,YAAY,EAAE,eAAe;IAC7B,YAAY,EAAE,qBAAqB;IACnC,8BAA8B;IAC9B,YAAY,EAAE,iBAAiB;IAC/B,YAAY,EAAE,iBAAiB;IAC/B,YAAY,EAAE,mBAAmB;IACjC,YAAY,EAAE,+BAA+B;IAC7C,YAAY,EAAE,yBAAyB;IACvC,YAAY,EAAE,+BAA+B;IAC7C,+BAA+B;IAC/B,YAAY,EAAE,eAAe;IAC7B,YAAY,EAAE,aAAa;IAC3B,YAAY,EAAE,cAAc;IAC5B,8BAA8B;IAC9B,YAAY,EAAE,cAAc;IAC5B,YAAY,EAAE,cAAc;IAC5B,YAAY,EAAE,sBAAsB;IACpC,YAAY,EAAE,cAAc;IAC5B,YAAY,EAAE,qBAAqB;IACnC,YAAY,EAAE,mCAAmC;IACjD,YAAY,EAAE,mBAAmB;IACjC,qBAAqB;IACrB,YAAY,EAAE,cAAc;IAC5B,YAAY,EAAE,WAAW;IACzB,YAAY,EAAE,aAAa;IAC3B,YAAY,EAAE,cAAc;IAC5B,gBAAgB;IAChB,YAAY,EAAE,cAAc;CAC5B,CAAC;AAEF;;GAEG;AACH,MAAM,mBAAmB,GAAG;IAC3B,eAAe;IACf,SAAS;IACT,cAAc;IACd,WAAW;IACX,cAAc;IACd,WAAW;CACX,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,kBAAkB,CAAC,KAAU;IAC5C,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;IACnC,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;IAEpD,gCAAgC;IAChC,MAAM,cAAc,GAAG,mBAAmB,CAAC,IAAI,CAC9C,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,CACjE,CAAC;IAEF,IAAI,SAA6B,CAAC;IAClC,IAAI,SAA4B,CAAC;IAEjC,qCAAqC;IACrC,IAAI,KAAK,CAAC,IAAI,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAClD,IAAI,CAAC;YACJ,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC9C,SAAS,GAAG,eAAe,CAAC,aAAa,CAAC,CAAC;QAC5C,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACZ,wBAAwB;QACzB,CAAC;IACF,CAAC;IAED,oDAAoD;IACpD,IAAI,CAAC,SAAS,IAAI,YAAY,EAAE,CAAC;QAChC,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;YAC/C,IAAI,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACjC,SAAS,GAAG,IAAI,CAAC;YAClB,CAAC;QACF,CAAC,CAAC,CAAC;IACJ,CAAC;IAED,+BAA+B;IAC/B,MAAM,eAAe,GAAG,SAAS;QAChC,CAAC,CAAC,uBAAuB,CAAC,SAAS,CAAC;QACpC,CAAC,CAAC,YAAY,CAAC;IAEhB,OAAO;QACN,OAAO,EAAE,eAAe;QACxB,cAAc;QACd,SAAS;QACT,SAAS;KACT,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,uBAAuB,CAAC,SAAiB;IACjD,QAAQ,SAAS,EAAE,CAAC;QACnB,qBAAqB;QACrB,KAAK,iBAAiB;YACrB,OAAO,oCAAoC,CAAC;QAC7C,KAAK,iBAAiB;YACrB,OAAO,+BAA+B,CAAC;QACxC,KAAK,mBAAmB;YACvB,OAAO,0DAA0D,CAAC;QACnE,KAAK,+BAA+B;YACnC,OAAO,yDAAyD,CAAC;QAClE,KAAK,yBAAyB;YAC7B,OAAO,6DAA6D,CAAC;QACtE,KAAK,+BAA+B;YACnC,OAAO,oEAAoE,CAAC;QAE7E,qBAAqB;QACrB,KAAK,oBAAoB;YACxB,OAAO,uBAAuB,CAAC;QAChC,KAAK,wBAAwB;YAC5B,OAAO,uBAAuB,CAAC;QAChC,KAAK,sBAAsB;YAC1B,OAAO,uDAAuD,CAAC;QAChE,KAAK,qBAAqB;YACzB,OAAO,wBAAwB,CAAC;QACjC,KAAK,uBAAuB;YAC3B,OAAO,0BAA0B,CAAC;QACnC,KAAK,4BAA4B;YAChC,OAAO,sEAAsE,CAAC;QAC/E,KAAK,uBAAuB;YAC3B,OAAO,0BAA0B,CAAC;QACnC,KAAK,uBAAuB;YAC3B,OAAO,0BAA0B,CAAC;QACnC,KAAK,gBAAgB;YACpB,OAAO,uBAAuB,CAAC;QAChC,KAAK,cAAc;YAClB,OAAO,uCAAuC,CAAC;QAChD,KAAK,eAAe;YACnB,OAAO,4BAA4B,CAAC;QACrC,KAAK,qBAAqB;YACzB,OAAO,mDAAmD,CAAC;QAE5D,sBAAsB;QACtB,KAAK,eAAe;YACnB,OAAO,gBAAgB,CAAC;QACzB,KAAK,aAAa;YACjB,OAAO,oBAAoB,CAAC;QAC7B,KAAK,cAAc;YAClB,OAAO,2BAA2B,CAAC;QAEpC,qBAAqB;QACrB,KAAK,cAAc;YAClB,OAAO,kEAAkE,CAAC;QAC3E,KAAK,cAAc;YAClB,OAAO,uEAAuE,CAAC;QAChF,KAAK,sBAAsB;YAC1B,OAAO,8DAA8D,CAAC;QACvE,KAAK,cAAc;YAClB,OAAO,kFAAkF,CAAC;QAC3F,KAAK,qBAAqB;YACzB,OAAO,uEAAuE,CAAC;QAChF,KAAK,mCAAmC;YACvC,OAAO,gEAAgE,CAAC;QACzE,KAAK,mBAAmB;YACvB,OAAO,mEAAmE,CAAC;QAE5E,qBAAqB;QACrB,KAAK,cAAc;YAClB,OAAO,iDAAiD,CAAC;QAC1D,KAAK,WAAW;YACf,OAAO,qEAAqE,CAAC;QAC9E,KAAK,aAAa;YACjB,OAAO,oDAAoD,CAAC;QAC7D,KAAK,cAAc;YAClB,OAAO,oEAAoE,CAAC;QAE7E,gBAAgB;QAChB,KAAK,cAAc;YAClB,OAAO,iEAAiE,CAAC;QAE1E;YACC,OAAO,mBAAmB,SAAS,EAAE,CAAC;IACxC,CAAC;AACF,CAAC"}

package/dist/utils/tag-abi-codec.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Tag ABI Codec
+ * Unified encoding/decoding utility for Tag values
+ *
+ * Key Principle: ALL values use abi.encode()
+ * - Simple values: abi.encode("value")
+ * - Arrays: abi.encode(["a", "b", "c"])
+ * - Tuples: abi.encode(struct)
+ * - Elements for push: abi.encode(singleElement)
+ */
+export declare class TagAbiCodec {
+    private static abiCoder;
+    /**
+     * Parse tuple field types from ABI type string
+     * @param abiType e.g., "tuple(string,uint8,tuple(bool,address))"
+     * @returns Array of field types: ["string", "uint8", "tuple(bool,address)"]
+     */
+    private static parseTupleFields;
+    /**
+     * Convert object to array based on ABI type structure
+     * Supports nested tuples recursively
+     *
+     * @param abiType ABI type string
+     * @param value Value (can be object or array)
+     * @returns Array value
+     */
+    private static convertObjectToArray;
+    /**
+     * Encode a value with given ABI type
+     *
+     * @param abiType ABI type string (e.g., "string", "uint256", "tuple(string,uint8)")
+     * @param value Value to encode (objects are automatically converted to arrays)
+     * @returns Encoded bytes (with 0x prefix)
+     *
+     * @example
+     * // Simple value
+     * TagAbiCodec.encode("string", "hello");
+     *
+     * // Array value
+     * TagAbiCodec.encode("string[]", ["a", "b", "c"]);
+     *
+     * // Tuple with object input
+     * TagAbiCodec.encode("tuple(string,uint8)", {name: "Alice", age: 30});
+     *
+     * // Nested tuple with object input
+     * TagAbiCodec.encode(
+     *   "tuple(string,tuple(uint8,bool))",
+     *   {name: "Alice", profile: {age: 30, verified: true}}
+     * );
+     *
+     * // Tuple with array input (still supported)
+     * TagAbiCodec.encode("tuple(string,uint8)", ["Alice", 30]);
+     */
+    static encode(abiType: string, value: any): string;
+    /**
+     * Decode bytes with given ABI type
+     *
+     * @param abiType ABI type string
+     * @param encodedData Encoded bytes (with or without 0x prefix)
+     * @returns Decoded value
+     *
+     * @example
+     * TagAbiCodec.decode("string", encodedBytes);  // → "hello"
+     * TagAbiCodec.decode("uint256", encodedBytes); // → 123n (BigInt)
+     * TagAbiCodec.decode("tuple(string,uint8)", encodedBytes); // → ["Alice", 30n]
+     */
+    static decode(abiType: string, encodedData: string): any;
+}
+//# sourceMappingURL=tag-abi-codec.d.ts.map

package/dist/utils/tag-abi-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-abi-codec.d.ts","sourceRoot":"","sources":["../../src/utils/tag-abi-codec.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,qBAAa,WAAW;IACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAkB;IAEzC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAkC/B;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IA6CnC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,MAAM;IAQlD;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,GAAG;CAIxD"}

package/dist/utils/tag-abi-codec.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TagAbiCodec = void 0;
+const ethers_1 = require("ethers");
+/**
+ * Tag ABI Codec
+ * Unified encoding/decoding utility for Tag values
+ *
+ * Key Principle: ALL values use abi.encode()
+ * - Simple values: abi.encode("value")
+ * - Arrays: abi.encode(["a", "b", "c"])
+ * - Tuples: abi.encode(struct)
+ * - Elements for push: abi.encode(singleElement)
+ */
+class TagAbiCodec {
+    /**
+     * Parse tuple field types from ABI type string
+     * @param abiType e.g., "tuple(string,uint8,tuple(bool,address))"
+     * @returns Array of field types: ["string", "uint8", "tuple(bool,address)"]
+     */
+    static parseTupleFields(abiType) {
+        if (!abiType.startsWith('tuple(')) {
+            return [];
+        }
+        const innerTypes = abiType.slice(6, -1); // Remove "tuple(" and ")"
+        const fields = [];
+        let depth = 0;
+        let currentField = '';
+        for (let i = 0; i < innerTypes.length; i++) {
+            const char = innerTypes[i];
+            if (char === '(') {
+                depth++;
+                currentField += char;
+            }
+            else if (char === ')') {
+                depth--;
+                currentField += char;
+            }
+            else if (char === ',' && depth === 0) {
+                fields.push(currentField.trim());
+                currentField = '';
+            }
+            else {
+                currentField += char;
+            }
+        }
+        if (currentField) {
+            fields.push(currentField.trim());
+        }
+        return fields;
+    }
+    /**
+     * Convert object to array based on ABI type structure
+     * Supports nested tuples recursively
+     *
+     * @param abiType ABI type string
+     * @param value Value (can be object or array)
+     * @returns Array value
+     */
+    static convertObjectToArray(abiType, value) {
+        // If already an array or not an object, return as-is
+        if (Array.isArray(value) ||
+            typeof value !== 'object' ||
+            value === null) {
+            return value;
+        }
+        // If not a tuple type, return as-is
+        if (!abiType.startsWith('tuple(')) {
+            return value;
+        }
+        // Parse tuple field types
+        const fieldTypes = this.parseTupleFields(abiType);
+        const fieldNames = Object.keys(value);
+        if (fieldNames.length !== fieldTypes.length) {
+            throw new Error(`Tuple field count mismatch: expected ${fieldTypes.length} fields, got ${fieldNames.length} (${fieldNames.join(', ')})`);
+        }
+        // Convert object to array, recursively handling nested tuples
+        const result = [];
+        for (let i = 0; i < fieldNames.length; i++) {
+            const fieldName = fieldNames[i];
+            const fieldType = fieldTypes[i];
+            const fieldValue = value[fieldName];
+            // Recursively convert nested tuples
+            if (fieldType.startsWith('tuple(')) {
+                result.push(this.convertObjectToArray(fieldType, fieldValue));
+            }
+            else {
+                result.push(fieldValue);
+            }
+        }
+        return result;
+    }
+    /**
+     * Encode a value with given ABI type
+     *
+     * @param abiType ABI type string (e.g., "string", "uint256", "tuple(string,uint8)")
+     * @param value Value to encode (objects are automatically converted to arrays)
+     * @returns Encoded bytes (with 0x prefix)
+     *
+     * @example
+     * // Simple value
+     * TagAbiCodec.encode("string", "hello");
+     *
+     * // Array value
+     * TagAbiCodec.encode("string[]", ["a", "b", "c"]);
+     *
+     * // Tuple with object input
+     * TagAbiCodec.encode("tuple(string,uint8)", {name: "Alice", age: 30});
+     *
+     * // Nested tuple with object input
+     * TagAbiCodec.encode(
+     *   "tuple(string,tuple(uint8,bool))",
+     *   {name: "Alice", profile: {age: 30, verified: true}}
+     * );
+     *
+     * // Tuple with array input (still supported)
+     * TagAbiCodec.encode("tuple(string,uint8)", ["Alice", 30]);
+     */
+    static encode(abiType, value) {
+        // Convert object to array if needed (handles nested tuples recursively)
+        const convertedValue = this.convertObjectToArray(abiType, value);
+        // Use ethers AbiCoder to encode
+        return this.abiCoder.encode([abiType], [convertedValue]);
+    }
+    /**
+     * Decode bytes with given ABI type
+     *
+     * @param abiType ABI type string
+     * @param encodedData Encoded bytes (with or without 0x prefix)
+     * @returns Decoded value
+     *
+     * @example
+     * TagAbiCodec.decode("string", encodedBytes);  // → "hello"
+     * TagAbiCodec.decode("uint256", encodedBytes); // → 123n (BigInt)
+     * TagAbiCodec.decode("tuple(string,uint8)", encodedBytes); // → ["Alice", 30n]
+     */
+    static decode(abiType, encodedData) {
+        const decoded = this.abiCoder.decode([abiType], encodedData);
+        return decoded[0];
+    }
+}
+exports.TagAbiCodec = TagAbiCodec;
+TagAbiCodec.abiCoder = new ethers_1.AbiCoder();
+//# sourceMappingURL=tag-abi-codec.js.map

package/dist/utils/tag-abi-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-abi-codec.js","sourceRoot":"","sources":["../../src/utils/tag-abi-codec.ts"],"names":[],"mappings":"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"}

package/dist/utils/tag-type-builder.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Tag Type Builder
+ * Calculate ABI type bytes offline without contract calls
+ * Does NOT handle encoding/decoding - use TagAbiCodec for that
+ *
+ * Encoding Rules:
+ * - uint: 0x01 + size (size = bits/8)
+ * - int: 0x00 + size
+ * - bool: 0x02
+ * - string: 0x03
+ * - array: 0x04 + elementType
+ * - fixedArray: 0x05 + length (2 bytes) + elementType
+ * - tuple: 0x06 + fieldCount (2 bytes) + fieldTypes...
+ * - address: 0x07
+ * - fixedBytes: 0x08 + size
+ * - bytes: 0x09
+ */
+export declare class TagTypeBuilder {
+    private typeBytes;
+    private abiTypeString;
+    protected constructor(typeBytes: string, abiTypeString?: string);
+    /**
+     * Get ABI type bytes (without 0x prefix)
+     */
+    getTypeBytes(): string;
+    /**
+     * Get ABI type string (e.g., "string", "uint256", "tuple(string,uint8)")
+     */
+    getAbiTypeString(): string;
+    /**
+     * Parse type bytes to ABI type string
+     * This is the reverse operation of building type bytes
+     * @param typeBytes Hex string of type bytes (with or without 0x prefix)
+     * @returns ABI type string
+     */
+    static parseTypeBytesToAbiString(typeBytes: string): string;
+    /**
+     * Calculate the byte length of a type bytes string (without 0x prefix)
+     * @private
+     */
+    private static getTypeBytesLength;
+    /**
+     * Get field names (for Tuple types)
+     * Returns format: string[][], each element is a tuple's field name array
+     */
+    getFieldNames(): string[][];
+    /**
+     * uint type
+     * @param bits Bit count: 8, 16, 24, ..., 256 (must be divisible by 8)
+     * @example
+     * TagTypeBuilder.uint(8)   → "0101"
+     * TagTypeBuilder.uint(256) → "0120"
+     */
+    static uint(bits?: number): TagTypeBuilder;
+    /**
+     * int type
+     * @param bits Bit count: 8, 16, 24, ..., 256 (must be divisible by 8)
+     * @example
+     * TagTypeBuilder.int(8)   → "0001"
+     * TagTypeBuilder.int(256) → "0020"
+     */
+    static int(bits?: number): TagTypeBuilder;
+    /**
+     * bool type
+     * @example
+     * TagTypeBuilder.bool() → "02"
+     */
+    static bool(): TagTypeBuilder;
+    /**
+     * string type
+     * @example
+     * TagTypeBuilder.string() → "03"
+     */
+    static string(): TagTypeBuilder;
+    /**
+     * address type
+     * @example
+     * TagTypeBuilder.address() → "07"
+     */
+    static address(): TagTypeBuilder;
+    /**
+     * bytes type (dynamic length)
+     * @example
+     * TagTypeBuilder.bytes() → "09"
+     */
+    static bytes(): TagTypeBuilder;
+    /**
+     * bytesN type (fixed length)
+     * @param size Byte count: 1-32
+     * @example
+     * TagTypeBuilder.fixedBytes(32) → "0820"
+     */
+    static fixedBytes(size: number): TagTypeBuilder;
+    /**
+     * Dynamic array
+     * @param elementType Element type
+     * @example
+     * TagTypeBuilder.array(TagTypeBuilder.address()) → "0407"
+     */
+    static array(elementType: TagTypeBuilder): TagTypeBuilder;
+    /**
+     * Fixed-length array
+     * @param elementType Element type
+     * @param length Array length (1-65535)
+     * @example
+     * TagTypeBuilder.fixedArray(TagTypeBuilder.address(), 5) → "05000507"
+     */
+    static fixedArray(elementType: TagTypeBuilder, length: number): TagTypeBuilder;
+    /**
+     * tuple type
+     * @param fields Field definitions, format: { fieldName: fieldType }
+     * @example
+     * TagTypeBuilder.tuple({
+     *   name: TagTypeBuilder.string(),
+     *   age: TagTypeBuilder.uint8()
+     * }) → "060002" + "03" + "0101"
+     *
+     * Field names are collected in pre-order traversal (DFS pre-order) for nested tuples.
+     * Pre-order: Visit root first, then recursively visit children left-to-right.
+     *
+     * Example tree structure: A{B{D{E, F}}, C}
+     * fieldNames = [
+     *   ["i", "j"],  // A's fields (root)
+     *   ["i"],       // B's fields (A's 1st child)
+     *   ["i", "j"],  // D's fields (B's child)
+     *   ["i", "j"],  // E's fields (D's 1st child)
+     *   ["i", "j"],  // F's fields (D's 2nd child)
+     *   ["i"]        // C's fields (A's 2nd child)
+     * ]
+     */
+    static tuple(fields: Record<string, TagTypeBuilder>): TupleTypeBuilder;
+    static uint8(): TagTypeBuilder;
+    static uint16(): TagTypeBuilder;
+    static uint32(): TagTypeBuilder;
+    static uint64(): TagTypeBuilder;
+    static uint128(): TagTypeBuilder;
+    static uint256(): TagTypeBuilder;
+    static int8(): TagTypeBuilder;
+    static int16(): TagTypeBuilder;
+    static int32(): TagTypeBuilder;
+    static int64(): TagTypeBuilder;
+    static int128(): TagTypeBuilder;
+    static int256(): TagTypeBuilder;
+    static bytes32(): TagTypeBuilder;
+    static addressArray(): TagTypeBuilder;
+    static stringArray(): TagTypeBuilder;
+    static uint256Array(): TagTypeBuilder;
+}
+/**
+ * Tuple Type Builder (supports field names and object encoding)
+ */
+export declare class TupleTypeBuilder extends TagTypeBuilder {
+    private fieldNames;
+    private fieldTypes?;
+    constructor(typeBytes: string, fieldNames: string[][], abiTypeString?: string, fieldTypes?: Record<string, TagTypeBuilder>);
+    getFieldNames(): string[][];
+}
+//# sourceMappingURL=tag-type-builder.d.ts.map

package/dist/utils/tag-type-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-type-builder.d.ts","sourceRoot":"","sources":["../../src/utils/tag-type-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,cAAc;IAC1B,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,aAAa,CAAc;IAEnC,SAAS,aAAa,SAAS,EAAE,MAAM,EAAE,aAAa,GAAE,MAAW;IAKnE;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;;;;OAKG;IACH,MAAM,CAAC,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAsF3D;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAgDjC;;;OAGG;IACH,aAAa,IAAI,MAAM,EAAE,EAAE;IAS3B;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,CAAC,IAAI,GAAE,MAAY,GAAG,cAAc;IAS/C;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAC,IAAI,GAAE,MAAY,GAAG,cAAc;IAS9C;;;;OAIG;IACH,MAAM,CAAC,IAAI,IAAI,cAAc;IAI7B;;;;OAIG;IACH,MAAM,CAAC,MAAM,IAAI,cAAc;IAI/B;;;;OAIG;IACH,MAAM,CAAC,OAAO,IAAI,cAAc;IAIhC;;;;OAIG;IACH,MAAM,CAAC,KAAK,IAAI,cAAc;IAI9B;;;;;OAKG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;IAY/C;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,cAAc,GAAG,cAAc;IAYzD;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,CAChB,WAAW,EAAE,cAAc,EAC3B,MAAM,EAAE,MAAM,GACZ,cAAc;IAoBjB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,gBAAgB;IAyCtE,MAAM,CAAC,KAAK;IAGZ,MAAM,CAAC,MAAM;IAGb,MAAM,CAAC,MAAM;IAGb,MAAM,CAAC,MAAM;IAGb,MAAM,CAAC,OAAO;IAGd,MAAM,CAAC,OAAO;IAId,MAAM,CAAC,IAAI;IAGX,MAAM,CAAC,KAAK;IAGZ,MAAM,CAAC,KAAK;IAGZ,MAAM,CAAC,KAAK;IAGZ,MAAM,CAAC,MAAM;IAGb,MAAM,CAAC,MAAM;IAIb,MAAM,CAAC,OAAO;IAId,MAAM,CAAC,YAAY;IAGnB,MAAM,CAAC,WAAW;IAGlB,MAAM,CAAC,YAAY;CAGnB;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,cAAc;IACnD,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAC,CAAiC;gBAGnD,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAAE,EAAE,EACtB,aAAa,GAAE,MAAW,EAC1B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC;IAO5C,aAAa,IAAI,MAAM,EAAE,EAAE;CAG3B"}