@aboutcircles/sdk-utils 0.1.0

package/dist/abi.d.ts

@@ -0,0 +1,31 @@
+import type { Abi } from 'abitype';
+import type { Hex } from '@aboutcircles/sdk-types';
+/**
+ * Convert an Ethereum address to EIP-55 checksummed format
+ * @param address - The address to checksum (with or without 0x prefix)
+ * @returns The checksummed address with 0x prefix
+ */
+export declare function checksumAddress(address: string): string;
+export declare function encodeFunctionData(config: {
+    abi: Abi;
+    functionName: string;
+    args?: readonly unknown[];
+}): Hex;
+export declare function decodeFunctionResult(config: {
+    abi: Abi;
+    functionName: string;
+    data: string;
+}): unknown;
+/**
+ * Decode error data from a contract revert
+ * @param config - Configuration with ABI and error data
+ * @returns Decoded error with name and arguments
+ */
+export declare function decodeErrorResult(config: {
+    abi: Abi;
+    data: string;
+}): {
+    errorName: string;
+    args?: any[];
+} | null;
+//# sourceMappingURL=abi.d.ts.map

package/dist/abi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abi.d.ts","sourceRoot":"","sources":["../src/abi.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,GAAG,EAAe,MAAM,SAAS,CAAC;AAChD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,yBAAyB,CAAC;AAwCnD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASvD;AAoXD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,GAAG,EAAE,GAAG,CAAC;IACT,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CAC3B,GAAG,GAAG,CA+DN;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,GAAG,EAAE,GAAG,CAAC;IACT,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CA0CV;AAmBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,GAAG,EAAE,GAAG,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;CACd,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;CAAE,GAAG,IAAI,CA+C7C"}

package/dist/abi.js

@@ -0,0 +1,448 @@
+import { keccak_256 } from '@noble/hashes/sha3.js';
+import { bytesToHex } from './bytes';
+// ============================================================================
+// CONSTANTS & UTILITIES
+// ============================================================================
+const HEX_CHARS = 64; // 32 bytes = 64 hex characters
+const BYTES_PER_WORD = 32;
+/** Remove 0x prefix efficiently */
+const strip0x = (hex) => hex.startsWith('0x') ? hex.slice(2) : hex;
+/** Pad hex string to 64 characters (32 bytes) */
+const pad64 = (hex) => hex.padStart(HEX_CHARS, '0');
+/** Convert number to padded hex */
+const toHex64 = (num) => num.toString(16).padStart(HEX_CHARS, '0');
+// ============================================================================
+// ADDRESS CHECKSUMMING (EIP-55)
+// ============================================================================
+/**
+ * Convert an Ethereum address to EIP-55 checksummed format
+ * @param address - The address to checksum (with or without 0x prefix)
+ * @returns The checksummed address with 0x prefix
+ */
+export function checksumAddress(address) {
+    const addr = address.toLowerCase().replace('0x', '');
+    const hash = bytesToHex(keccak_256(new TextEncoder().encode(addr))).slice(2);
+    let result = '0x';
+    for (let i = 0; i < addr.length; i++) {
+        result += parseInt(hash[i], 16) >= 8 ? addr[i].toUpperCase() : addr[i];
+    }
+    return result;
+}
+// ============================================================================
+// FUNCTION SIGNATURE & SELECTOR
+// ============================================================================
+function getTypeString(type, components) {
+    if (type === 'tuple' && components) {
+        const types = components.map(c => getTypeString(c.type, c.components));
+        return `(${types.join(',')})`;
+    }
+    // Handle tuple arrays: tuple[] or tuple[N]
+    const tupleArrayMatch = type.match(/^tuple(\[\d*\])$/);
+    if (tupleArrayMatch && components) {
+        const baseType = getTypeString('tuple', components);
+        return `${baseType}${tupleArrayMatch[1]}`;
+    }
+    return type;
+}
+function getFunctionSignature(abiFunction) {
+    const inputs = abiFunction.inputs || [];
+    const types = inputs.map(input => getTypeString(input.type, input.components));
+    return `${abiFunction.name}(${types.join(',')})`;
+}
+function getFunctionSelector(abiFunction) {
+    const signature = getFunctionSignature(abiFunction);
+    const hash = keccak_256(new TextEncoder().encode(signature));
+    return bytesToHex(hash.slice(0, 4));
+}
+// ============================================================================
+// DYNAMIC TYPE DETECTION
+// ============================================================================
+function isDynamicType(type, components) {
+    // String and bytes are always dynamic
+    if (type === 'string' || type === 'bytes')
+        return true;
+    // Dynamic arrays (including fixed arrays of dynamic elements)
+    if (type.includes('[')) {
+        const baseType = type.slice(0, type.indexOf('['));
+        // Dynamic length array is always dynamic
+        if (type.endsWith('[]'))
+            return true;
+        // Fixed array is dynamic if its elements are dynamic
+        if (baseType === 'tuple') {
+            return isTupleDynamic(components);
+        }
+        return isDynamicType(baseType);
+    }
+    // Tuple is dynamic if any component is dynamic
+    if (type === 'tuple') {
+        return isTupleDynamic(components);
+    }
+    return false;
+}
+function isTupleDynamic(components) {
+    return components?.some(c => isDynamicType(c.type, c.components)) ?? false;
+}
+// ============================================================================
+// ENCODING
+// ============================================================================
+function encodeParam(type, value, components) {
+    // Handle tuples
+    if (type === 'tuple' && components) {
+        return encodeTuple(components, value);
+    }
+    // Handle arrays
+    if (type.includes('[')) {
+        return encodeArray(type, value, components);
+    }
+    // Handle primitives
+    return encodePrimitive(type, value);
+}
+function encodeArray(type, arr, components) {
+    const baseType = type.slice(0, type.indexOf('['));
+    const isDynamic = type.endsWith('[]');
+    const elementsAreDynamic = isDynamicType(baseType, components);
+    let encoded;
+    if (elementsAreDynamic) {
+        // Encode with offsets for dynamic elements
+        const encodings = arr.map(v => encodeParam(baseType, v, components));
+        let offset = arr.length * BYTES_PER_WORD;
+        const offsets = encodings.map(enc => {
+            const currentOffset = offset;
+            offset += enc.length / 2;
+            return toHex64(currentOffset);
+        });
+        encoded = offsets.join('') + encodings.join('');
+    }
+    else {
+        // Encode inline for static elements
+        encoded = arr.map(v => encodeParam(baseType, v, components)).join('');
+    }
+    // Prepend length for dynamic arrays
+    return isDynamic ? toHex64(arr.length) + encoded : encoded;
+}
+function encodeTuple(components, value) {
+    const isArray = Array.isArray(value);
+    const encodings = [];
+    const dynamicData = [];
+    const isDynamic = [];
+    // First pass: encode all components
+    for (let i = 0; i < components.length; i++) {
+        const component = components[i];
+        const val = isArray ? value[i] : value[component.name || ''];
+        const dynamic = isDynamicType(component.type, component.components);
+        isDynamic.push(dynamic);
+        if (dynamic) {
+            encodings.push(''); // Placeholder for offset
+            dynamicData.push(encodeParam(component.type, val, component.components));
+        }
+        else {
+            encodings.push(encodeParam(component.type, val, component.components));
+        }
+    }
+    // Second pass: calculate offsets and build result
+    if (dynamicData.length > 0) {
+        let offset = encodings.reduce((sum, enc, i) => sum + (isDynamic[i] ? BYTES_PER_WORD : enc.length / 2), 0);
+        let result = '';
+        let dynamicIndex = 0;
+        for (let i = 0; i < components.length; i++) {
+            if (isDynamic[i]) {
+                result += toHex64(offset);
+                offset += dynamicData[dynamicIndex].length / 2;
+                dynamicIndex++;
+            }
+            else {
+                result += encodings[i];
+            }
+        }
+        return result + dynamicData.join('');
+    }
+    return encodings.join('');
+}
+function encodePrimitive(type, value) {
+    // Address
+    if (type === 'address') {
+        return strip0x(value).toLowerCase().padStart(HEX_CHARS, '0');
+    }
+    // Boolean
+    if (type === 'bool') {
+        return toHex64(value ? 1 : 0);
+    }
+    // Unsigned integers
+    if (type.startsWith('uint')) {
+        const num = typeof value === 'bigint' ? value : BigInt(value);
+        return toHex64(num);
+    }
+    // Signed integers
+    if (type.startsWith('int')) {
+        let num = typeof value === 'bigint' ? value : BigInt(value);
+        if (num < 0n) {
+            const bits = type === 'int' ? 256 : parseInt(type.slice(3));
+            num = (1n << BigInt(bits)) + num; // Two's complement
+        }
+        return toHex64(num);
+    }
+    // Fixed-length bytes (bytes1-bytes32)
+    if (type.startsWith('bytes') && type !== 'bytes') {
+        return strip0x(value).padEnd(HEX_CHARS, '0');
+    }
+    // Dynamic bytes
+    if (type === 'bytes') {
+        const bytes = strip0x(value);
+        const length = toHex64(bytes.length / 2);
+        const padded = bytes.padEnd(Math.ceil(bytes.length / HEX_CHARS) * HEX_CHARS, '0');
+        return length + padded;
+    }
+    // String
+    if (type === 'string') {
+        const bytes = Array.from(new TextEncoder().encode(value))
+            .map(b => b.toString(16).padStart(2, '0'))
+            .join('');
+        const length = toHex64(bytes.length / 2);
+        const padded = bytes.padEnd(Math.ceil(bytes.length / HEX_CHARS) * HEX_CHARS, '0');
+        return length + padded;
+    }
+    throw new Error(`Unsupported type: ${type}`);
+}
+function decodeParam(type, data, offset = 0, components) {
+    // Handle tuples
+    if (type === 'tuple' && components) {
+        return decodeTuple(components, data, offset);
+    }
+    // Handle arrays
+    if (type.includes('[')) {
+        return decodeArray(type, data, offset, components);
+    }
+    // Handle primitives
+    return decodePrimitive(type, data, offset);
+}
+function decodeArray(type, data, offset, components) {
+    const baseType = type.slice(0, type.indexOf('['));
+    const chunk = data.slice(offset, offset + HEX_CHARS);
+    // Dynamic array
+    if (type.endsWith('[]')) {
+        const dataOffset = parseInt(chunk, 16) * 2;
+        const length = parseInt(data.slice(dataOffset, dataOffset + HEX_CHARS), 16);
+        const values = [];
+        let currentOffset = dataOffset + HEX_CHARS;
+        for (let i = 0; i < length; i++) {
+            const result = decodeParam(baseType, data, currentOffset, components);
+            values.push(result.value);
+            currentOffset += result.consumed;
+        }
+        return { value: values, consumed: HEX_CHARS };
+    }
+    // Fixed array
+    const match = type.match(/\[(\d+)\]$/);
+    if (match) {
+        const length = parseInt(match[1]);
+        const values = [];
+        let consumed = 0;
+        for (let i = 0; i < length; i++) {
+            const result = decodeParam(baseType, data, offset + consumed, components);
+            values.push(result.value);
+            consumed += result.consumed;
+        }
+        return { value: values, consumed };
+    }
+    throw new Error(`Invalid array type: ${type}`);
+}
+function decodeTuple(components, data, offset) {
+    const values = [];
+    let currentOffset = offset;
+    for (const component of components) {
+        const result = decodeParam(component.type, data, currentOffset, component.components);
+        values.push(result.value);
+        currentOffset += result.consumed;
+    }
+    return { value: values, consumed: currentOffset - offset };
+}
+function decodePrimitive(type, data, offset) {
+    const chunk = data.slice(offset, offset + HEX_CHARS);
+    // Address
+    if (type === 'address') {
+        return {
+            value: checksumAddress('0x' + chunk.slice(24)),
+            consumed: HEX_CHARS
+        };
+    }
+    // Boolean
+    if (type === 'bool') {
+        return {
+            value: parseInt(chunk, 16) !== 0,
+            consumed: HEX_CHARS
+        };
+    }
+    // Unsigned integers
+    if (type.startsWith('uint')) {
+        return {
+            value: BigInt('0x' + chunk),
+            consumed: HEX_CHARS
+        };
+    }
+    // Signed integers
+    if (type.startsWith('int')) {
+        const value = BigInt('0x' + chunk);
+        const bits = type === 'int' ? 256 : parseInt(type.slice(3));
+        const signBit = 1n << BigInt(bits - 1);
+        return {
+            value: value >= signBit ? value - (1n << BigInt(bits)) : value,
+            consumed: HEX_CHARS
+        };
+    }
+    // Fixed-length bytes
+    if (type.startsWith('bytes') && type !== 'bytes') {
+        const size = parseInt(type.match(/^bytes(\d+)$/)[1]);
+        return {
+            value: '0x' + chunk.slice(0, size * 2),
+            consumed: HEX_CHARS
+        };
+    }
+    // Dynamic bytes
+    if (type === 'bytes') {
+        const dataOffset = parseInt(chunk, 16) * 2;
+        const length = parseInt(data.slice(dataOffset, dataOffset + HEX_CHARS), 16) * 2;
+        return {
+            value: '0x' + data.slice(dataOffset + HEX_CHARS, dataOffset + HEX_CHARS + length),
+            consumed: HEX_CHARS
+        };
+    }
+    // String
+    if (type === 'string') {
+        const dataOffset = parseInt(chunk, 16) * 2;
+        const length = parseInt(data.slice(dataOffset, dataOffset + HEX_CHARS), 16) * 2;
+        const bytes = data.slice(dataOffset + HEX_CHARS, dataOffset + HEX_CHARS + length);
+        const byteArray = new Uint8Array(bytes.match(/.{2}/g)?.map(b => parseInt(b, 16)) || []);
+        return {
+            value: new TextDecoder().decode(byteArray),
+            consumed: HEX_CHARS
+        };
+    }
+    throw new Error(`Unsupported type: ${type}`);
+}
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+export function encodeFunctionData(config) {
+    const { abi, functionName, args = [] } = config;
+    const abiFunction = abi.find(item => item.type === 'function' && item.name === functionName);
+    if (!abiFunction) {
+        throw new Error(`Function "${functionName}" not found in ABI`);
+    }
+    const selector = getFunctionSelector(abiFunction);
+    const inputs = abiFunction.inputs || [];
+    if (inputs.length === 0)
+        return selector;
+    if (args.length !== inputs.length) {
+        throw new Error(`Expected ${inputs.length} arguments, got ${args.length}`);
+    }
+    // Encode parameters
+    const encodings = [];
+    const dynamicData = [];
+    const isDynamic = [];
+    for (let i = 0; i < inputs.length; i++) {
+        const input = inputs[i];
+        const components = input.components;
+        const dynamic = isDynamicType(input.type, components);
+        isDynamic.push(dynamic);
+        if (dynamic) {
+            encodings.push('');
+            dynamicData.push(encodeParam(input.type, args[i], components));
+        }
+        else {
+            encodings.push(encodeParam(input.type, args[i], components));
+        }
+    }
+    // Calculate offsets and build result
+    if (dynamicData.length === 0) {
+        return (selector + encodings.join(''));
+    }
+    let offset = encodings.reduce((sum, enc, i) => sum + (isDynamic[i] ? BYTES_PER_WORD : enc.length / 2), 0);
+    let result = '';
+    let dynamicIndex = 0;
+    for (let i = 0; i < inputs.length; i++) {
+        if (isDynamic[i]) {
+            result += toHex64(offset);
+            offset += dynamicData[dynamicIndex].length / 2;
+            dynamicIndex++;
+        }
+        else {
+            result += encodings[i];
+        }
+    }
+    return (selector + result + dynamicData.join(''));
+}
+export function decodeFunctionResult(config) {
+    const { abi, functionName, data } = config;
+    const abiFunction = abi.find(item => item.type === 'function' && item.name === functionName);
+    if (!abiFunction) {
+        throw new Error(`Function "${functionName}" not found in ABI`);
+    }
+    const outputs = abiFunction.outputs || [];
+    if (outputs.length === 0)
+        return undefined;
+    const cleanData = strip0x(data);
+    // Single output
+    if (outputs.length === 1) {
+        return decodeParam(outputs[0].type, cleanData, 0, outputs[0].components).value;
+    }
+    // Multiple outputs
+    const results = [];
+    let offset = 0;
+    for (const output of outputs) {
+        const result = decodeParam(output.type, cleanData, offset, output.components);
+        results.push(result.value);
+        offset += result.consumed;
+    }
+    return results;
+}
+// ============================================================================
+// ERROR DECODING
+// ============================================================================
+/**
+ * Get error selector (first 4 bytes) from error ABI item
+ */
+function getErrorSelector(errorItem) {
+    const inputs = errorItem.inputs || [];
+    const types = inputs.map((input) => getTypeString(input.type, input.components));
+    const signature = `${errorItem.name}(${types.join(',')})`;
+    const hash = keccak_256(new TextEncoder().encode(signature));
+    return bytesToHex(hash.slice(0, 4));
+}
+/**
+ * Decode error data from a contract revert
+ * @param config - Configuration with ABI and error data
+ * @returns Decoded error with name and arguments
+ */
+export function decodeErrorResult(config) {
+    const { abi, data } = config;
+    if (!data || data.length < 10) {
+        return null; // Not enough data for a selector
+    }
+    // Extract the error selector (first 4 bytes)
+    const selector = data.slice(0, 10).toLowerCase();
+    const cleanData = strip0x(data.slice(10));
+    // Find matching error in ABI
+    const errors = abi.filter(item => item.type === 'error');
+    for (const errorItem of errors) {
+        const errorSelector = getErrorSelector(errorItem);
+        if (errorSelector.toLowerCase() === selector) {
+            const inputs = errorItem.inputs || [];
+            if (inputs.length === 0) {
+                return { errorName: errorItem.name };
+            }
+            // Decode error parameters
+            const decodedArgs = [];
+            let offset = 0;
+            for (const input of inputs) {
+                const result = decodeParam(input.type, cleanData, offset, input.components);
+                decodedArgs.push(result.value);
+                offset += result.consumed;
+            }
+            return {
+                errorName: errorItem.name,
+                args: decodedArgs
+            };
+        }
+    }
+    return null; // No matching error found
+}

package/dist/address.d.ts

@@ -0,0 +1,10 @@
+import type { Address } from '@aboutcircles/sdk-types';
+/**
+ * Converts a uint256 value to an Ethereum address
+ * Takes the last 20 bytes of the uint256
+ *
+ * @param uint256 - The uint256 value as a bigint
+ * @returns The address as a checksummed hex string
+ */
+export declare function uint256ToAddress(uint256: bigint): Address;
+//# sourceMappingURL=address.d.ts.map

package/dist/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../src/address.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEvD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAYzD"}

package/dist/address.js

@@ -0,0 +1,17 @@
+/**
+ * Converts a uint256 value to an Ethereum address
+ * Takes the last 20 bytes of the uint256
+ *
+ * @param uint256 - The uint256 value as a bigint
+ * @returns The address as a checksummed hex string
+ */
+export function uint256ToAddress(uint256) {
+    // Convert bigint to hex string
+    const hex = uint256.toString(16);
+    // Pad to 64 characters (256 bits / 4 bits per hex char)
+    const paddedHex = hex.padStart(64, '0');
+    // Take the last 40 characters (20 bytes = 160 bits)
+    const addressHex = paddedHex.slice(-40);
+    // Add 0x prefix and return as lowercase (checksumming happens at consumer level if needed)
+    return `0x${addressHex}`;
+}

package/dist/bytes.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Convert a Uint8Array to a hex string with 0x prefix
+ */
+export declare function bytesToHex(bytes: Uint8Array): string;
+//# sourceMappingURL=bytes.d.ts.map

package/dist/bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../src/bytes.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAMpD"}

package/dist/bytes.js

@@ -0,0 +1,15 @@
+// Pre-computed lookup table for byte-to-hex conversion
+const byteToHex = [];
+for (let i = 0; i < 256; i++) {
+    byteToHex[i] = i.toString(16).padStart(2, '0');
+}
+/**
+ * Convert a Uint8Array to a hex string with 0x prefix
+ */
+export function bytesToHex(bytes) {
+    let hex = '0x';
+    for (let i = 0; i < bytes.length; i++) {
+        hex += byteToHex[bytes[i]];
+    }
+    return hex;
+}

package/dist/cid.d.ts

@@ -0,0 +1,39 @@
+import type { Hex } from '@aboutcircles/sdk-types';
+/**
+ * Convert a CIDv0 string to a bytes32 hex string for on-chain storage
+ *
+ * CIDv0 format:
+ * - Base58 encoded multihash
+ * - Always uses SHA-256 hash algorithm
+ * - Contains 32-byte hash digest
+ *
+ * This function is browser-compatible using the modern `multiformats` library.
+ *
+ * @param cidV0 - The CIDv0 string (e.g., "QmXxxx...")
+ * @returns The 32-byte hash digest as a hex string
+ * @throws Error if the CID is invalid or uses unsupported hash algorithm
+ *
+ * @example
+ * ```typescript
+ * const hex = cidV0ToHex('QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG');
+ * // Returns: '0x...' (32 bytes / 64 hex characters)
+ * ```
+ */
+export declare function cidV0ToHex(cidV0: string): Hex;
+/**
+ * Convert a CIDv0 string to a Uint8Array of the hash digest
+ *
+ * This function is browser-compatible using the modern `multiformats` library.
+ *
+ * @param cidV0 - The CIDv0 string (e.g., "QmXxxx...")
+ * @returns The 32-byte hash digest as a Uint8Array
+ * @throws Error if the CID is invalid or uses unsupported hash algorithm
+ *
+ * @example
+ * ```typescript
+ * const bytes = cidV0ToUint8Array('QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG');
+ * // Returns: Uint8Array(32) [...]
+ * ```
+ */
+export declare function cidV0ToUint8Array(cidV0: string): Uint8Array;
+//# sourceMappingURL=cid.d.ts.map

package/dist/cid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cid.d.ts","sourceRoot":"","sources":["../src/cid.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,yBAAyB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAmB7C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAgB3D"}

package/dist/cid.js

@@ -0,0 +1,67 @@
+import { CID } from 'multiformats/cid';
+import { base58btc } from 'multiformats/bases/base58';
+/**
+ * Convert a CIDv0 string to a bytes32 hex string for on-chain storage
+ *
+ * CIDv0 format:
+ * - Base58 encoded multihash
+ * - Always uses SHA-256 hash algorithm
+ * - Contains 32-byte hash digest
+ *
+ * This function is browser-compatible using the modern `multiformats` library.
+ *
+ * @param cidV0 - The CIDv0 string (e.g., "QmXxxx...")
+ * @returns The 32-byte hash digest as a hex string
+ * @throws Error if the CID is invalid or uses unsupported hash algorithm
+ *
+ * @example
+ * ```typescript
+ * const hex = cidV0ToHex('QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG');
+ * // Returns: '0x...' (32 bytes / 64 hex characters)
+ * ```
+ */
+export function cidV0ToHex(cidV0) {
+    // Parse the CIDv0 string using base58btc decoder
+    const cid = CID.parse(cidV0, base58btc);
+    // Verify this is CIDv0
+    if (cid.version !== 0) {
+        throw new Error(`Expected CIDv0, got CIDv${cid.version}`);
+    }
+    // Verify the multihash uses SHA-256 (code: 0x12)
+    if (cid.multihash.code !== 0x12) {
+        throw new Error('Unsupported hash algorithm. Only SHA-256 is supported for CIDv0.');
+    }
+    // Extract the 32-byte hash digest and convert to hex
+    const digest = cid.multihash.digest;
+    const hexString = `0x${Array.from(digest).map(b => b.toString(16).padStart(2, '0')).join('')}`;
+    return hexString;
+}
+/**
+ * Convert a CIDv0 string to a Uint8Array of the hash digest
+ *
+ * This function is browser-compatible using the modern `multiformats` library.
+ *
+ * @param cidV0 - The CIDv0 string (e.g., "QmXxxx...")
+ * @returns The 32-byte hash digest as a Uint8Array
+ * @throws Error if the CID is invalid or uses unsupported hash algorithm
+ *
+ * @example
+ * ```typescript
+ * const bytes = cidV0ToUint8Array('QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG');
+ * // Returns: Uint8Array(32) [...]
+ * ```
+ */
+export function cidV0ToUint8Array(cidV0) {
+    // Parse the CIDv0 string using base58btc decoder
+    const cid = CID.parse(cidV0, base58btc);
+    // Verify this is CIDv0
+    if (cid.version !== 0) {
+        throw new Error(`Expected CIDv0, got CIDv${cid.version}`);
+    }
+    // Verify the multihash uses SHA-256 (code: 0x12)
+    if (cid.multihash.code !== 0x12) {
+        throw new Error('Unsupported hash algorithm. Only SHA-256 is supported for CIDv0.');
+    }
+    // Extract and return the 32-byte hash digest
+    return cid.multihash.digest;
+}