@cheny56/node-client 1.0.0

package/src/transaction.js

@@ -0,0 +1,566 @@
+/**
+ * Transaction Builders
+ * Supports Legacy, AccessList, DynamicFee transactions with ECDSA, PQC, and Hybrid signatures
+ */
+
+import { ethers } from 'ethers';
+import { ml_dsa65 } from '@noble/post-quantum/ml-dsa';
+import { TX_TYPE, PQC_TYPE, DEFAULT_CHAIN_ID } from './constants.js';
+import { encodeUint64, encodeBigInt, encodeSignature } from './utils/rlp.js';
+
+/**
+ * Base Transaction class
+ */
+class BaseTransaction {
+    constructor(params) {
+        this.chainId = params.chainId || DEFAULT_CHAIN_ID;
+        this.nonce = params.nonce || 0;
+        this.to = params.to;
+        this.value = params.value || 0n;
+        this.data = params.data || '0x';
+    }
+}
+
+/**
+ * Legacy ECDSA Transaction (Type 0)
+ */
+export class LegacyTransaction extends BaseTransaction {
+    constructor(params) {
+        super(params);
+        this.type = TX_TYPE.LEGACY;
+        this.gasPrice = params.gasPrice || 0n;
+        this.gasLimit = params.gasLimit || 21000n;
+    }
+
+    /**
+     * Sign with ECDSA wallet
+     * @param {ECDSAWallet} wallet - ECDSA wallet
+     * @returns {Promise<string>} Signed transaction (hex)
+     */
+    async sign(wallet) {
+        const tx = {
+            type: 0,
+            nonce: this.nonce,
+            gasPrice: this.gasPrice,
+            gasLimit: this.gasLimit,
+            to: this.to,
+            value: this.value,
+            data: this.data,
+            chainId: this.chainId,
+        };
+        return await wallet.wallet.signTransaction(tx);
+    }
+
+    /**
+     * Get hex-encoded serialized transaction
+     * @param {ECDSAWallet} wallet - ECDSA wallet
+     * @returns {Promise<string>} Serialized transaction (hex)
+     */
+    async getHex(wallet) {
+        return await this.sign(wallet);
+    }
+}
+
+/**
+ * Legacy PQC-only Transaction (Type 0 with PQC)
+ */
+export class PQCLegacyTransaction extends BaseTransaction {
+    constructor(params) {
+        super(params);
+        this.type = TX_TYPE.LEGACY;
+        this.gasPrice = params.gasPrice || 0n;
+        this.gasLimit = params.gasLimit || 21000n;
+        this.pqcType = PQC_TYPE.DILITHIUM;
+        this.pqcPubKey = null;
+        this.pqcSig = null;
+        this.v = 0;
+        this.r = '0x0';
+        this.s = '0x0';
+    }
+
+    getSigningHash() {
+        const nonceBytes = this.nonce === 0n || this.nonce === 0 
+            ? new Uint8Array(0) 
+            : ethers.getBytes(ethers.toBeHex(this.nonce));
+        const gasLimitBytes = this.gasLimit === 0n || this.gasLimit === 0
+            ? new Uint8Array(0)
+            : ethers.getBytes(ethers.toBeHex(this.gasLimit));
+        const chainIdBytes = this.chainId === 0n || this.chainId === 0
+            ? new Uint8Array(0)
+            : ethers.getBytes(ethers.toBeHex(this.chainId));
+
+        const encoded = ethers.encodeRlp([
+            nonceBytes,
+            this.gasPrice === 0n ? new Uint8Array(0) : ethers.getBytes(ethers.toBeHex(this.gasPrice)),
+            gasLimitBytes,
+            this.to || '0x',
+            this.value === 0n ? new Uint8Array(0) : ethers.getBytes(ethers.toBeHex(this.value)),
+            this.data,
+            chainIdBytes,
+            new Uint8Array(0),
+            new Uint8Array(0),
+        ]);
+        return ethers.keccak256(encoded);
+    }
+
+    /**
+     * Sign with PQC wallet
+     * @param {PQCWallet} wallet - PQC wallet
+     * @returns {PQCLegacyTransaction} This transaction
+     */
+    sign(wallet) {
+        const hash = ethers.getBytes(this.getSigningHash());
+        this.pqcPubKey = wallet.publicKey;
+        const ctx = new TextEncoder().encode('ML-DSA-65');
+        this.pqcSig = ml_dsa65.sign(wallet.secretKey, hash, ctx);
+        this.v = Number(this.chainId) * 2 + 35;
+        this.r = '0x0';
+        this.s = '0x0';
+        return this;
+    }
+
+    verify() {
+        if (!this.pqcSig || !this.pqcPubKey) return false;
+        const hash = ethers.getBytes(this.getSigningHash());
+        const ctx = new TextEncoder().encode('ML-DSA-65');
+        return ml_dsa65.verify(this.pqcPubKey, hash, this.pqcSig, ctx);
+    }
+
+    serialize() {
+        if (!this.pqcSig) throw new Error('Transaction not signed');
+        if (!this.pqcPubKey || this.pqcPubKey.length === 0 || !this.pqcSig || this.pqcSig.length === 0) {
+            throw new Error('PQC fields are required');
+        }
+
+        const nonceHex = encodeUint64(this.nonce);
+        const gasPriceHex = encodeBigInt(this.gasPrice);
+        const gasLimitHex = encodeUint64(this.gasLimit);
+        const valueHex = encodeBigInt(this.value);
+        const vHex = encodeBigInt(this.v || 0);
+        const rHex = encodeSignature(this.r || '0x0');
+        const sHex = encodeSignature(this.s || '0x0');
+        const pqcTypeHex = encodeUint64(this.pqcType);
+
+        const encoded = ethers.encodeRlp([
+            nonceHex,
+            gasPriceHex,
+            gasLimitHex,
+            this.to || '0x',
+            valueHex,
+            this.data || '0x',
+            vHex,
+            rHex,
+            sHex,
+            pqcTypeHex,
+            this.pqcPubKey,
+            this.pqcSig,
+        ]);
+        return ethers.getBytes(encoded);
+    }
+
+    getHex() {
+        return ethers.hexlify(this.serialize());
+    }
+}
+
+/**
+ * Legacy Hybrid Transaction (Type 0 with ECDSA + PQC)
+ */
+export class HybridLegacyTransaction extends BaseTransaction {
+    constructor(params) {
+        super(params);
+        this.type = TX_TYPE.LEGACY;
+        this.gasPrice = params.gasPrice || 0n;
+        this.gasLimit = params.gasLimit || 21000n;
+        this.pqcType = PQC_TYPE.DILITHIUM;
+        this.pqcPubKey = null;
+        this.pqcSig = null;
+        this.v = null;
+        this.r = null;
+        this.s = null;
+    }
+
+    getSigningHash() {
+        const nonceBytes = this.nonce === 0n || this.nonce === 0 
+            ? new Uint8Array(0) 
+            : ethers.getBytes(ethers.toBeHex(this.nonce));
+        const gasLimitBytes = this.gasLimit === 0n || this.gasLimit === 0
+            ? new Uint8Array(0)
+            : ethers.getBytes(ethers.toBeHex(this.gasLimit));
+        const chainIdBytes = this.chainId === 0n || this.chainId === 0
+            ? new Uint8Array(0)
+            : ethers.getBytes(ethers.toBeHex(this.chainId));
+
+        const encoded = ethers.encodeRlp([
+            nonceBytes,
+            this.gasPrice === 0n ? new Uint8Array(0) : ethers.getBytes(ethers.toBeHex(this.gasPrice)),
+            gasLimitBytes,
+            this.to || '0x',
+            this.value === 0n ? new Uint8Array(0) : ethers.getBytes(ethers.toBeHex(this.value)),
+            this.data,
+            chainIdBytes,
+            new Uint8Array(0),
+            new Uint8Array(0),
+        ]);
+        return ethers.keccak256(encoded);
+    }
+
+    /**
+     * Sign with both ECDSA and PQC wallets
+     * @param {ECDSAWallet} ecdsaWallet - ECDSA wallet
+     * @param {PQCWallet} pqcWallet - PQC wallet
+     * @returns {HybridLegacyTransaction} This transaction
+     */
+    sign(ecdsaWallet, pqcWallet) {
+        const hash = this.getSigningHash();
+        const hashBytes = ethers.getBytes(hash);
+
+        // ECDSA signature
+        const ecdsaSig = ecdsaWallet.wallet.signingKey.sign(hash);
+        const recoveryId = ecdsaSig.v >= 27 ? ecdsaSig.v - 27 : ecdsaSig.v;
+        this.v = Number(this.chainId) * 2 + 35 + recoveryId;
+        this.r = ecdsaSig.r;
+        this.s = ecdsaSig.s;
+
+        // PQC signature
+        const ctx = new TextEncoder().encode('ML-DSA-65');
+        this.pqcPubKey = pqcWallet.publicKey;
+        this.pqcSig = ml_dsa65.sign(pqcWallet.secretKey, hashBytes, ctx);
+
+        return this;
+    }
+
+    verify() {
+        if (!this.pqcSig || !this.pqcPubKey) return false;
+        const hash = ethers.getBytes(this.getSigningHash());
+        const ctx = new TextEncoder().encode('ML-DSA-65');
+        return ml_dsa65.verify(this.pqcPubKey, hash, this.pqcSig, ctx);
+    }
+
+    serialize() {
+        if (!this.pqcSig || !this.r) throw new Error('Transaction not signed');
+        if (!this.pqcPubKey || this.pqcPubKey.length === 0 || !this.pqcSig || this.pqcSig.length === 0) {
+            throw new Error('PQC fields are required');
+        }
+
+        const nonceHex = encodeUint64(this.nonce);
+        const gasPriceHex = encodeBigInt(this.gasPrice);
+        const gasLimitHex = encodeUint64(this.gasLimit);
+        const valueHex = encodeBigInt(this.value);
+        const vHex = encodeBigInt(this.v);
+        const rHex = encodeSignature(this.r);
+        const sHex = encodeSignature(this.s);
+        const pqcTypeHex = encodeUint64(this.pqcType);
+
+        const encoded = ethers.encodeRlp([
+            nonceHex,
+            gasPriceHex,
+            gasLimitHex,
+            this.to || '0x',
+            valueHex,
+            this.data || '0x',
+            vHex,
+            rHex,
+            sHex,
+            pqcTypeHex,
+            this.pqcPubKey,
+            this.pqcSig,
+        ]);
+        return ethers.getBytes(encoded);
+    }
+
+    getHex() {
+        return ethers.hexlify(this.serialize());
+    }
+}
+
+/**
+ * AccessList Transaction (Type 1) - ECDSA
+ */
+export class AccessListTransaction extends BaseTransaction {
+    constructor(params) {
+        super(params);
+        this.type = TX_TYPE.ACCESS_LIST;
+        this.gasPrice = params.gasPrice || 0n;
+        this.gasLimit = params.gasLimit || 21000n;
+        this.accessList = params.accessList || [];
+    }
+
+    async sign(wallet) {
+        const tx = {
+            type: 1,
+            nonce: this.nonce,
+            gasPrice: this.gasPrice,
+            gasLimit: this.gasLimit,
+            to: this.to,
+            value: this.value,
+            data: this.data,
+            accessList: this.accessList,
+            chainId: this.chainId,
+        };
+        return await wallet.wallet.signTransaction(tx);
+    }
+
+    async getHex(wallet) {
+        return await this.sign(wallet);
+    }
+}
+
+/**
+ * AccessList PQC Transaction (Type 1 with PQC)
+ */
+export class PQCAccessListTransaction extends BaseTransaction {
+    constructor(params) {
+        super(params);
+        this.type = TX_TYPE.ACCESS_LIST;
+        this.gasPrice = params.gasPrice || 0n;
+        this.gasLimit = params.gasLimit || 21000n;
+        this.accessList = params.accessList || [];
+        this.pqcType = PQC_TYPE.DILITHIUM;
+        this.pqcPubKey = null;
+        this.pqcSig = null;
+        this.v = 0;
+        this.r = '0x0';
+        this.s = '0x0';
+    }
+
+    getSigningHash() {
+        const chainIdHex = this.chainId === 0n || this.chainId === 0 ? '0x' : ethers.toBeHex(this.chainId);
+        const nonceHex = this.nonce === 0n || this.nonce === 0 ? '0x' : ethers.toBeHex(this.nonce);
+        const gasPriceHex = this.gasPrice === 0n || this.gasPrice === 0 ? '0x' : ethers.toBeHex(this.gasPrice);
+        const gasHex = this.gasLimit === 0n || this.gasLimit === 0 ? '0x' : ethers.toBeHex(this.gasLimit);
+        const valueHex = this.value === 0n || this.value === 0 ? '0x' : ethers.toBeHex(this.value);
+
+        const rlpData = [
+            chainIdHex,
+            nonceHex,
+            gasPriceHex,
+            gasHex,
+            this.to || null,
+            valueHex,
+            this.data || '0x',
+            this.accessList || [],
+        ];
+
+        const encodedHex = ethers.encodeRlp(rlpData);
+        const encoded = ethers.getBytes(encodedHex);
+
+        const typeByte = TX_TYPE.ACCESS_LIST;
+        const prefixed = new Uint8Array(1 + encoded.length);
+        prefixed[0] = typeByte;
+        prefixed.set(encoded, 1);
+
+        return ethers.keccak256(ethers.hexlify(prefixed));
+    }
+
+    sign(wallet) {
+        const hash = ethers.getBytes(this.getSigningHash());
+        this.pqcPubKey = wallet.publicKey;
+        const ctx = new TextEncoder().encode('ML-DSA-65');
+        this.pqcSig = ml_dsa65.sign(wallet.secretKey, hash, ctx);
+        return this;
+    }
+
+    verify() {
+        if (!this.pqcSig || !this.pqcPubKey) return false;
+        const hash = ethers.getBytes(this.getSigningHash());
+        const ctx = new TextEncoder().encode('ML-DSA-65');
+        return ml_dsa65.verify(this.pqcPubKey, hash, this.pqcSig, ctx);
+    }
+
+    serialize() {
+        if (!this.pqcSig) throw new Error('Transaction not signed');
+        if (!this.pqcPubKey || this.pqcPubKey.length === 0 || !this.pqcSig || this.pqcSig.length === 0) {
+            throw new Error('PQC fields are required');
+        }
+
+        const toAddress = this.to && this.to !== '0x' && this.to !== null ? this.to : null;
+        const chainIdHex = encodeBigInt(this.chainId);
+        const nonceHex = encodeUint64(this.nonce);
+        const gasPriceHex = encodeBigInt(this.gasPrice);
+        const gasLimitHex = encodeUint64(this.gasLimit);
+        const valueHex = encodeBigInt(this.value);
+        const vHex = encodeBigInt(this.v || 0);
+        const rHex = encodeSignature(this.r || '0x0');
+        const sHex = encodeSignature(this.s || '0x0');
+        const pqcTypeHex = encodeUint64(this.pqcType);
+
+        const encoded = ethers.encodeRlp([
+            chainIdHex,
+            nonceHex,
+            gasPriceHex,
+            gasLimitHex,
+            toAddress,
+            valueHex,
+            this.data || '0x',
+            this.accessList || [],
+            vHex,
+            rHex,
+            sHex,
+            pqcTypeHex,
+            this.pqcPubKey,
+            this.pqcSig,
+        ]);
+
+        const encodedBytes = ethers.getBytes(encoded);
+        const typeByte = new Uint8Array([TX_TYPE.ACCESS_LIST]);
+        const prefixed = new Uint8Array(typeByte.length + encodedBytes.length);
+        prefixed.set(typeByte, 0);
+        prefixed.set(encodedBytes, typeByte.length);
+
+        return prefixed;
+    }
+
+    getHex() {
+        return ethers.hexlify(this.serialize());
+    }
+}
+
+/**
+ * DynamicFee Transaction (Type 2) - ECDSA
+ */
+export class DynamicFeeTransaction extends BaseTransaction {
+    constructor(params) {
+        super(params);
+        this.type = TX_TYPE.DYNAMIC_FEE;
+        this.maxPriorityFeePerGas = params.maxPriorityFeePerGas || 0n;
+        this.maxFeePerGas = params.maxFeePerGas || 0n;
+        this.gasLimit = params.gasLimit || 21000n;
+        this.accessList = params.accessList || [];
+    }
+
+    async sign(wallet) {
+        const tx = {
+            type: 2,
+            nonce: this.nonce,
+            maxPriorityFeePerGas: this.maxPriorityFeePerGas,
+            maxFeePerGas: this.maxFeePerGas,
+            gasLimit: this.gasLimit,
+            to: this.to,
+            value: this.value,
+            data: this.data,
+            accessList: this.accessList,
+            chainId: this.chainId,
+        };
+        return await wallet.wallet.signTransaction(tx);
+    }
+
+    async getHex(wallet) {
+        return await this.sign(wallet);
+    }
+}
+
+/**
+ * DynamicFee PQC Transaction (Type 2 with PQC)
+ */
+export class PQCDynamicFeeTransaction extends BaseTransaction {
+    constructor(params) {
+        super(params);
+        this.type = TX_TYPE.DYNAMIC_FEE;
+        this.maxPriorityFeePerGas = params.maxPriorityFeePerGas || 0n;
+        this.maxFeePerGas = params.maxFeePerGas || 0n;
+        this.gasLimit = params.gasLimit || 21000n;
+        this.accessList = params.accessList || [];
+        this.pqcType = PQC_TYPE.DILITHIUM;
+        this.pqcPubKey = null;
+        this.pqcSig = null;
+        this.v = 0;
+        this.r = '0x0';
+        this.s = '0x0';
+    }
+
+    getSigningHash() {
+        const chainIdHex = this.chainId === 0n || this.chainId === 0 ? '0x' : ethers.toBeHex(this.chainId);
+        const nonceHex = this.nonce === 0n || this.nonce === 0 ? '0x' : ethers.toBeHex(this.nonce);
+        const gasTipCapHex = this.maxPriorityFeePerGas === 0n || this.maxPriorityFeePerGas === 0 ? '0x' : ethers.toBeHex(this.maxPriorityFeePerGas);
+        const gasFeeCapHex = this.maxFeePerGas === 0n || this.maxFeePerGas === 0 ? '0x' : ethers.toBeHex(this.maxFeePerGas);
+        const gasHex = this.gasLimit === 0n || this.gasLimit === 0 ? '0x' : ethers.toBeHex(this.gasLimit);
+        const valueHex = this.value === 0n || this.value === 0 ? '0x' : ethers.toBeHex(this.value);
+
+        const rlpData = [
+            chainIdHex,
+            nonceHex,
+            gasTipCapHex,
+            gasFeeCapHex,
+            gasHex,
+            this.to || null,
+            valueHex,
+            this.data || '0x',
+            this.accessList || [],
+        ];
+
+        const encodedHex = ethers.encodeRlp(rlpData);
+        const encoded = ethers.getBytes(encodedHex);
+
+        const typeByte = TX_TYPE.DYNAMIC_FEE;
+        const prefixed = new Uint8Array(1 + encoded.length);
+        prefixed[0] = typeByte;
+        prefixed.set(encoded, 1);
+
+        return ethers.keccak256(ethers.hexlify(prefixed));
+    }
+
+    sign(wallet) {
+        const hash = ethers.getBytes(this.getSigningHash());
+        this.pqcPubKey = wallet.publicKey;
+        const ctx = new TextEncoder().encode('ML-DSA-65');
+        this.pqcSig = ml_dsa65.sign(wallet.secretKey, hash, ctx);
+        return this;
+    }
+
+    verify() {
+        if (!this.pqcSig || !this.pqcPubKey) return false;
+        const hash = ethers.getBytes(this.getSigningHash());
+        const ctx = new TextEncoder().encode('ML-DSA-65');
+        return ml_dsa65.verify(this.pqcPubKey, hash, this.pqcSig, ctx);
+    }
+
+    serialize() {
+        if (!this.pqcSig) throw new Error('Transaction not signed');
+        if (!this.pqcPubKey || this.pqcPubKey.length === 0 || !this.pqcSig || this.pqcSig.length === 0) {
+            throw new Error('PQC fields are required');
+        }
+
+        const toAddress = this.to && this.to !== '0x' && this.to !== null ? this.to : null;
+        const chainIdHex = encodeBigInt(this.chainId);
+        const nonceHex = encodeUint64(this.nonce);
+        const gasTipCapHex = encodeBigInt(this.maxPriorityFeePerGas);
+        const gasFeeCapHex = encodeBigInt(this.maxFeePerGas);
+        const gasLimitHex = encodeUint64(this.gasLimit);
+        const valueHex = encodeBigInt(this.value);
+        const vHex = encodeBigInt(this.v || 0);
+        const rHex = encodeSignature(this.r || '0x0');
+        const sHex = encodeSignature(this.s || '0x0');
+        const pqcTypeHex = encodeUint64(this.pqcType);
+
+        const encoded = ethers.encodeRlp([
+            chainIdHex,
+            nonceHex,
+            gasTipCapHex,
+            gasFeeCapHex,
+            gasLimitHex,
+            toAddress,
+            valueHex,
+            this.data || '0x',
+            this.accessList || [],
+            vHex,
+            rHex,
+            sHex,
+            pqcTypeHex,
+            this.pqcPubKey,
+            this.pqcSig,
+        ]);
+
+        const encodedBytes = ethers.getBytes(encoded);
+        const typeByte = new Uint8Array([TX_TYPE.DYNAMIC_FEE]);
+        const prefixed = new Uint8Array(typeByte.length + encodedBytes.length);
+        prefixed.set(typeByte, 0);
+        prefixed.set(encodedBytes, typeByte.length);
+
+        return prefixed;
+    }
+
+    getHex() {
+        return ethers.hexlify(this.serialize());
+    }
+}

package/src/utils/address.js

@@ -0,0 +1,48 @@
+/**
+ * Address Utilities
+ * Handles address derivation for PQC and Hybrid addresses
+ */
+
+import { ethers } from 'ethers';
+
+/**
+ * Derive PQC address from Dilithium public key
+ * @param {Uint8Array} publicKey - Dilithium public key
+ * @returns {string} Ethereum address
+ */
+export function derivePQCAddress(publicKey) {
+    const hash = ethers.keccak256(publicKey);
+    return ethers.getAddress('0x' + hash.slice(-40));
+}
+
+/**
+ * Derive Hybrid address from ECDSA and Dilithium public keys
+ * @param {Uint8Array} ecdsaPublicKey - ECDSA public key (65 bytes, remove 0x04 prefix)
+ * @param {Uint8Array} dilithiumPublicKey - Dilithium public key
+ * @returns {string} Hybrid Ethereum address
+ */
+export function deriveHybridAddress(ecdsaPublicKey, dilithiumPublicKey) {
+    // Remove 0x04 prefix from ECDSA public key if present
+    let ecdsaBytes = ecdsaPublicKey;
+    if (ecdsaBytes.length === 65 && ecdsaBytes[0] === 4) {
+        ecdsaBytes = ecdsaBytes.slice(1); // 64 bytes
+    }
+
+    // Concatenate ECDSA (64 bytes) + Dilithium public key
+    const concat = new Uint8Array(ecdsaBytes.length + dilithiumPublicKey.length);
+    concat.set(ecdsaBytes, 0);
+    concat.set(dilithiumPublicKey, ecdsaBytes.length);
+
+    // Hash and derive address
+    const hash = ethers.keccak256(concat);
+    return ethers.getAddress('0x' + hash.slice(-40));
+}
+
+/**
+ * Validate Ethereum address format
+ * @param {string} address - Address to validate
+ * @returns {boolean}
+ */
+export function isValidAddress(address) {
+    return ethers.utils.isAddress(address);
+}

package/src/utils/rlp.js

@@ -0,0 +1,56 @@
+/**
+ * RLP Encoding Utilities
+ * Handles proper encoding for Go RLP compatibility
+ */
+
+import { ethers } from 'ethers';
+
+/**
+ * Encode uint64 value for RLP as hex string
+ * In Go RLP, uint64(0) encodes as empty bytes, non-zero as canonical bytes
+ */
+export function encodeUint64(value) {
+    if (value === 0 || value === 0n || value === null || value === undefined) {
+        return '0x';
+    }
+    const bigValue = typeof value === 'bigint' ? value : BigInt(value);
+    return ethers.toBeHex(bigValue);
+}
+
+/**
+ * Encode *big.Int value for RLP as hex string
+ * Go RLP encodes *big.Int(0) as 0x80 (empty bytes), NOT 0x00!
+ */
+export function encodeBigInt(value) {
+    if (value === 0 || value === 0n || value === null || value === undefined) {
+        return '0x';
+    }
+    const bigValue = typeof value === 'bigint' ? value : BigInt(value);
+    return ethers.toBeHex(bigValue);
+}
+
+/**
+ * Encode signature value (R, S) for RLP as hex string
+ * Removes leading zeros for canonical form (required for *big.Int in Go RLP)
+ */
+export function encodeSignature(value) {
+    if (!value || value === '0x0' || value === '0x' || value === '0x00') {
+        return '0x';
+    }
+
+    const hex = value.startsWith('0x') ? value : '0x' + value;
+    let bytes = ethers.getBytes(hex);
+
+    // Remove leading zeros for canonical form
+    let startIdx = 0;
+    while (startIdx < bytes.length && bytes[startIdx] === 0) {
+        startIdx++;
+    }
+
+    if (startIdx === bytes.length) {
+        return '0x';
+    }
+
+    bytes = bytes.slice(startIdx);
+    return ethers.hexlify(bytes);
+}