@odatano/core 0.3.16 → 0.3.18

package/srv/blockchain/transaction-building/csl-tx.js

@@ -64,373 +64,94 @@ class CSLTxBuilder {
         logger.info(`Initialized with protocol parameters.`);
     }
     /**
-     * Build unsigned ADA transfer transaction
-     * @param req transaction build request
-     * @param ctx transaction build context
-     * @returns {Promise<TxBuildResult>} transaction build result
+     * Build unsigned transfer transaction (ADA-only or with native assets)
      */
-    async buildUnsignedAdaTransfer(req, ctx) {
+    async buildUnsignedTransfer(req, ctx) {
         try {
-            // prepare addresses
             const recipientAddress = CSL.Address.from_bech32(req.recipientAddress);
             const changeAddress = CSL.Address.from_bech32(req.changeAddress ?? req.senderAddress);
-            // map ODATANO UTxOs -> CSL TransactionUnspentOutputs (with multi-asset support)
-            // This allows spending UTxOs that contain native assets - they will be returned in the change output
             const cslUtxos = this._mapMultiAssetUtxosToCslUtxos(ctx.utxos);
-            // create Transaction Builder from stored config
             const txb = CSL.TransactionBuilder.new(this.txBuilderConfig);
-            // add recipient & output (lovelace + optional assets), with optional inline datum
-            const amount = CSL.BigNum.from_str(String(req.lovelaceAmount));
-            const outValue = CSL.Value.new(amount);
-            // Optional: add native assets to the output (for locking tokens at script address)
+            // Build output value (lovelace + optional native assets)
+            const outValue = CSL.Value.new(CSL.BigNum.from_str(String(req.lovelaceAmount)));
             if (req.assets && req.assets.length > 0) {
-                const multiAsset = CSL.MultiAsset.new();
-                for (const asset of req.assets) {
-                    if (asset.unit === 'lovelace')
-                        continue;
-                    const { policyId, assetName } = (0, tx_build_helper_1.parseAssetUnit)(asset.unit);
-                    const policyHash = CSL.ScriptHash.from_bytes(Buffer.from(policyId, 'hex'));
-                    let assets = multiAsset.get(policyHash);
-                    if (!assets)
-                        assets = CSL.Assets.new();
-                    assets.insert(CSL.AssetName.new(Buffer.from(assetName, 'hex')), CSL.BigNum.from_str(asset.quantity));
-                    multiAsset.insert(policyHash, assets);
-                }
-                outValue.set_multiasset(multiAsset);
+                outValue.set_multiasset(this._buildCslMultiAsset(req.assets));
             }
             const out = CSL.TransactionOutput.new(recipientAddress, outValue);
-            if (req.outputDatum) {
-                const plutusData = CSL.PlutusData.from_json(JSON.stringify(req.outputDatum), CSL.PlutusDatumSchema.DetailedSchema);
-                out.set_plutus_data(plutusData);
-            }
+            this._attachInlineDatum(out, req.outputDatum);
             txb.add_output(out);
-            // add inputs via coin selection + add change
             txb.add_inputs_from(cslUtxos, CSL.CoinSelectionStrategyCIP2.LargestFirstMultiAsset);
             txb.add_change_if_needed(changeAddress);
-            // build unsigned tx
             const unsignedTx = txb.build_tx();
-            // Export the complete transaction (with empty witness set) for cardano-cli
-            const unsignedTxCbor = Buffer.from(unsignedTx.to_bytes()).toString("hex");
-            // hash + fee + outputs
-            const body = unsignedTx.body();
-            const bodyBytes = body.to_bytes();
-            const hash = (0, blake2b_1.default)(32).update(bodyBytes).digest('hex');
-            const txBodyHash = hash;
-            const feeLovelace = body.fee().to_str();
-            const outputs = [];
-            const txOuts = body.outputs();
-            for (let i = 0; i < txOuts.len(); i++) {
-                const o = txOuts.get(i);
-                outputs.push({
-                    address: o.address().to_bech32(),
-                    lovelace: o.amount().coin().to_str(),
-                });
-            }
+            const txDetails = this._extractTxDetails(unsignedTx);
             logger.info(`Built unsigned transaction successfully.`);
-            return {
-                unsignedTxCbor,
-                txBodyHash,
-                senderAddress: req.senderAddress,
-                network: this.cardanoClient.network,
-                sizeBytes: unsignedTxCbor.length / 2, // hex to bytes
-                builderEngine: this.name,
-                feeLovelace: feeLovelace,
-                inputs: ctx.utxos.map(u => ({
-                    txHash: u.txHash,
-                    index: u.outputIndex,
-                    lovelace: (0, tx_build_helper_1.getLovelace)(u).toString(),
-                })),
-                outputs,
-                warnings: [],
-            };
+            return this._buildResult(req, ctx, txDetails);
         }
         catch (err) {
-            (0, tx_build_helper_1.mapBuilderError)(err, 'lovelace');
+            (0, tx_build_helper_1.mapBuilderError)(err);
         }
     }
     async buildUnsignedTransactionWithMetadata(req, ctx) {
         try {
-            // prepare addresses
             const recipientAddress = CSL.Address.from_bech32(req.recipientAddress);
             const changeAddress = CSL.Address.from_bech32(req.changeAddress ?? req.senderAddress);
-            // map ODATANO UTxOs -> CSL TransactionUnspentOutputs (with multi-asset support)
-            // This allows spending UTxOs that contain native assets - they will be returned in the change output
             const cslUtxos = this._mapMultiAssetUtxosToCslUtxos(ctx.utxos);
-            // create Transaction Builder from stored config
             const txb = CSL.TransactionBuilder.new(this.txBuilderConfig);
-            // add recipient & output (lovelace)
             const amount = CSL.BigNum.from_str(String(req.lovelaceAmount));
             const outValue = CSL.Value.new(amount);
             const out = CSL.TransactionOutput.new(recipientAddress, outValue);
             txb.add_output(out);
-            // add metadata if provided
             if (req.metadataJson) {
                 const metadata = this._mapOdatanoMetadataToCSLMetadata(req.metadataJson);
                 txb.set_metadata(metadata);
             }
-            // add inputs via coin selection + add change
             txb.add_inputs_from(cslUtxos, CSL.CoinSelectionStrategyCIP2.LargestFirstMultiAsset);
             txb.add_change_if_needed(changeAddress);
-            // build unsigned tx
             const unsignedTx = txb.build_tx();
-            // Export the complete transaction (with empty witness set) for cardano-cli
-            const unsignedTxCbor = Buffer.from(unsignedTx.to_bytes()).toString("hex");
-            // hash + fee + outputs
-            const body = unsignedTx.body();
-            const bodyBytes = body.to_bytes();
-            const hash = (0, blake2b_1.default)(32).update(bodyBytes).digest('hex');
-            const txBodyHash = hash;
-            const feeLovelace = body.fee().to_str();
-            const outputs = [];
-            const txOuts = body.outputs();
-            for (let i = 0; i < txOuts.len(); i++) {
-                const o = txOuts.get(i);
-                outputs.push({
-                    address: o.address().to_bech32(),
-                    lovelace: o.amount().coin().to_str(),
-                });
-            }
+            const txDetails = this._extractTxDetails(unsignedTx);
             logger.info(`Built unsigned transaction with metadata successfully.`);
-            return {
-                unsignedTxCbor,
-                txBodyHash,
-                senderAddress: req.senderAddress,
-                network: this.cardanoClient.network,
-                sizeBytes: unsignedTxCbor.length / 2, // hex to bytes
-                builderEngine: this.name,
-                feeLovelace,
-                inputs: ctx.utxos.map(u => ({
-                    txHash: u.txHash,
-                    index: u.outputIndex,
-                    lovelace: (0, tx_build_helper_1.getLovelace)(u).toString(),
-                })),
-                outputs,
-                warnings: [],
-            };
-        }
-        catch (err) {
-            (0, tx_build_helper_1.mapBuilderError)(err, 'lovelace');
-        }
-    }
-    async buildUnsignedMultiAssetTransaction(req, ctx) {
-        if (!req.assets || req.assets.length === 0) {
-            throw new Error('[CSLTxBuilder] buildUnsignedMultiAssetTransaction requires assets to be specified');
-        }
-        try {
-            // prepare addresses
-            const recipientAddress = CSL.Address.from_bech32(req.recipientAddress);
-            const changeAddress = CSL.Address.from_bech32(req.changeAddress ?? req.senderAddress);
-            // map ODATANO UTxOs -> CSL TransactionUnspentOutputs (with multi-asset support)
-            const cslUtxos = this._mapMultiAssetUtxosToCslUtxos(ctx.utxos);
-            // create Transaction Builder from stored config
-            const txb = CSL.TransactionBuilder.new(this.txBuilderConfig);
-            // Build output value with ADA + multi-assets
-            const lovelace = CSL.BigNum.from_str(String(req.lovelaceAmount));
-            const outputValue = CSL.Value.new(lovelace);
-            // Create MultiAsset structure for native tokens
-            const multiAsset = CSL.MultiAsset.new();
-            for (const asset of req.assets) {
-                // Skip 'lovelace' unit (already handled above)
-                if (asset.unit === 'lovelace')
-                    continue;
-                const { policyId, assetName } = (0, tx_build_helper_1.parseAssetUnit)(asset.unit);
-                // Get or create Assets for this policy
-                const policyHash = CSL.ScriptHash.from_bytes(Buffer.from(policyId, 'hex'));
-                let assets = multiAsset.get(policyHash);
-                if (!assets) {
-                    assets = CSL.Assets.new();
-                }
-                // Add asset with quantity
-                const assetNameBytes = Buffer.from(assetName, 'hex');
-                const cslAssetName = CSL.AssetName.new(assetNameBytes);
-                const quantity = CSL.BigNum.from_str(asset.quantity);
-                assets.insert(cslAssetName, quantity);
-                multiAsset.insert(policyHash, assets);
-            }
-            // Set multi-asset on output value
-            outputValue.set_multiasset(multiAsset);
-            // Create output with all assets + optional inline datum
-            const recipientOutput = CSL.TransactionOutput.new(recipientAddress, outputValue);
-            if (req.outputDatum) {
-                const plutusData = CSL.PlutusData.from_json(JSON.stringify(req.outputDatum), CSL.PlutusDatumSchema.DetailedSchema);
-                recipientOutput.set_plutus_data(plutusData);
-            }
-            txb.add_output(recipientOutput);
-            // add inputs via coin selection + add change
-            txb.add_inputs_from(cslUtxos, CSL.CoinSelectionStrategyCIP2.LargestFirstMultiAsset);
-            txb.add_change_if_needed(changeAddress);
-            // build unsigned tx
-            const unsignedTx = txb.build_tx();
-            // Export the complete transaction (with empty witness set) for cardano-cli
-            const unsignedTxCbor = Buffer.from(unsignedTx.to_bytes()).toString("hex");
-            // hash + fee + outputs
-            const body = unsignedTx.body();
-            const bodyBytes = body.to_bytes();
-            const hash = (0, blake2b_1.default)(32).update(bodyBytes).digest('hex');
-            const txBodyHash = hash;
-            const feeLovelace = body.fee().to_str();
-            const outputs = [];
-            const txOuts = body.outputs();
-            for (let i = 0; i < txOuts.len(); i++) {
-                const o = txOuts.get(i);
-                outputs.push({
-                    address: o.address().to_bech32(),
-                    lovelace: o.amount().coin().to_str(),
-                });
-            }
-            logger.info(`Built unsigned multi-asset transaction successfully.`);
-            return {
-                unsignedTxCbor,
-                txBodyHash,
-                senderAddress: req.senderAddress,
-                network: this.cardanoClient.network,
-                sizeBytes: unsignedTxCbor.length / 2, // hex to bytes
-                builderEngine: this.name,
-                feeLovelace,
-                inputs: ctx.utxos.map(u => ({
-                    txHash: u.txHash,
-                    index: u.outputIndex,
-                    lovelace: (0, tx_build_helper_1.getLovelace)(u).toString(),
-                })),
-                outputs,
-                warnings: [],
-            };
+            return this._buildResult(req, ctx, txDetails);
         }
         catch (err) {
-            // Extract asset unit from error message if possible
-            const assetMatch = err?.message?.match(/not enough\s+([a-f0-9.]+)/i);
-            const assetUnit = assetMatch?.[1] || 'assets';
-            (0, tx_build_helper_1.mapBuilderError)(err, assetUnit);
+            (0, tx_build_helper_1.mapBuilderError)(err);
         }
     }
     async buildUnsignedMintTransaction(req, ctx) {
         try {
-            // Determine execution units based on evaluator availability
-            let finalExUnits = {
-                mem: String(const_1.DEFAULT_EXECUTION_UNITS.mem),
-                cpu: String(const_1.DEFAULT_EXECUTION_UNITS.cpu)
-            };
-            if (ctx.evaluateTransaction) {
-                // Build first pass with high execution units for evaluation
-                logger.debug(`[CSLTxBuilder] Building evaluation pass with high execution units`);
-                const evalTx = this._buildMintTx(req, ctx, {
-                    mem: String(const_1.HIGH_EXECUTION_UNITS.mem),
-                    cpu: String(const_1.HIGH_EXECUTION_UNITS.cpu)
-                });
-                const evalTxCbor = Buffer.from(evalTx.to_bytes()).toString('hex');
-                try {
-                    // Evaluate to get exact execution units
-                    const evalResults = await ctx.evaluateTransaction(evalTxCbor);
-                    logger.debug(`[CSLTxBuilder] Evaluation results: ${JSON.stringify(evalResults)}`);
-                    if (evalResults && evalResults.length > 0) {
-                        // Use the evaluated budget (take first result for single script)
-                        const budget = evalResults[0].budget;
-                        // Add safety margin to evaluated units
-                        finalExUnits = {
-                            mem: Math.ceil(budget.memory * const_1.EXECUTION_UNIT_BUFFER).toString(),
-                            cpu: Math.ceil(budget.cpu * const_1.EXECUTION_UNIT_BUFFER).toString()
-                        };
-                        logger.info(`[CSLTxBuilder] Using evaluated execution units: mem=${finalExUnits.mem}, cpu=${finalExUnits.cpu}`);
-                    }
-                }
-                catch (evalError) {
-                    logger.warn(`[CSLTxBuilder] Evaluation failed, using default units: ${evalError.message}`);
-                    // Fall back to defaults on evaluation failure
-                }
-            }
-            else {
-                logger.debug(`[CSLTxBuilder] No evaluator available, using default execution units`);
-            }
-            // Build final transaction with determined execution units
+            const finalExUnits = await this._evaluateExUnits((exUnits) => this._buildMintTx(req, ctx, exUnits), ctx.evaluateTransaction);
             const unsignedTx = this._buildMintTx(req, ctx, finalExUnits);
-            logger.debug(`[CSLTxBuilder] Transaction built successfully`);
-            // Export as CBOR hex
-            const unsignedTxCbor = Buffer.from(unsignedTx.to_bytes()).toString('hex');
-            // Extract transaction details from the transaction
-            const body = unsignedTx.body();
-            const bodyBytes = body.to_bytes();
-            const hash = (0, blake2b_1.default)(32).update(bodyBytes).digest('hex');
-            const txBodyHash = hash;
-            const feeLovelace = body.fee().to_str();
-            // Extract outputs
-            const outputs = [];
-            const txOuts = body.outputs();
-            for (let i = 0; i < txOuts.len(); i++) {
-                const o = txOuts.get(i);
-                outputs.push({
-                    address: o.address().to_bech32(),
-                    lovelace: o.amount().coin().to_str(),
-                });
-            }
-            // Compute script hash from the minting policy script (= policy ID)
-            const mintScriptBytes = Buffer.from(req.mintingPolicyScript, 'hex');
-            const mintPlutusScript = CSL.PlutusScript.new_v3(mintScriptBytes);
-            const mintScriptHash = Buffer.from(mintPlutusScript.hash().to_bytes()).toString('hex');
-            logger.info(`[CSLTxBuilder] Built unsigned minting transaction successfully. Fee: ${feeLovelace}`);
-            return {
-                unsignedTxCbor,
-                txBodyHash,
-                senderAddress: req.senderAddress,
-                network: this.cardanoClient.network,
-                sizeBytes: unsignedTxCbor.length / 2, // hex to bytes
-                builderEngine: this.name,
-                feeLovelace,
-                inputs: ctx.utxos.map(u => ({
-                    txHash: u.txHash,
-                    index: u.outputIndex,
-                    lovelace: (0, tx_build_helper_1.getLovelace)(u).toString(),
-                })),
-                outputs,
-                scriptHash: mintScriptHash,
-                warnings: [],
-            };
+            const txDetails = this._extractTxDetails(unsignedTx);
+            const { hashHex: scriptHash } = this._computeScriptHash(req.mintingPolicyScript);
+            logger.info(`Built unsigned minting transaction successfully. Fee: ${txDetails.feeLovelace}`);
+            return this._buildResult(req, ctx, txDetails, { scriptHash });
         }
         catch (error) {
-            logger.error(`[CSLTxBuilder] buildUnsignedMintTransaction error: ${error?.message || error}`);
-            (0, tx_build_helper_1.mapBuilderError)(error, 'lovelace');
+            logger.error(`BuildUnsignedMintTransaction error: ${error?.message || error}`);
+            (0, tx_build_helper_1.mapBuilderError)(error);
         }
     }
     /**
      * Helper to build mint transaction with specified execution units
      */
     _buildMintTx(req, ctx, exUnits) {
-        // Prepare addresses
         const recipientAddress = CSL.Address.from_bech32(req.recipientAddress);
         const changeAddress = CSL.Address.from_bech32(req.changeAddress ?? req.senderAddress);
-        // Create Transaction Builder
         const txb = CSL.TransactionBuilder.new(this.txBuilderConfig);
-        // Parse the Plutus script from CBOR hex (CBOR-wrapped flat UPLC bytecode)
-        const scriptBytes = Buffer.from(req.mintingPolicyScript, 'hex');
-        const plutusScript = CSL.PlutusScript.new_v3(scriptBytes);
-        const scriptHash = plutusScript.hash();
-        // Create PlutusScriptSource - wrapper for the script
+        const { plutusScript, cslHash: scriptHash } = this._computeScriptHash(req.mintingPolicyScript);
         const scriptSource = CSL.PlutusScriptSource.new(plutusScript);
-        // Create MintBuilder
+        // Create MintBuilder and track total minted value for output
         const mintBuilder = CSL.MintBuilder.new();
-        // Track total minted value for output
         let totalMintedValue = CSL.Value.new(CSL.BigNum.from_str('0'));
-        // Process each mint action
         for (const mintAction of req.mintActions) {
             const { assetName } = (0, tx_build_helper_1.parseAssetUnit)(mintAction.assetUnit);
-            // Create asset name
-            const assetNameBytes = Buffer.from(assetName, 'hex');
-            const cslAssetName = CSL.AssetName.new(assetNameBytes);
-            // Create mint quantity (can be negative for burning)
+            const cslAssetName = CSL.AssetName.new(Buffer.from(assetName, 'hex'));
             const mintQuantity = CSL.Int.new_i32(Number(mintAction.quantity));
-            // Create redeemer with specified execution units
-            let redeemerData;
-            if (req.mintRedeemer) {
-                redeemerData = CSL.PlutusData.from_json(JSON.stringify(req.mintRedeemer), CSL.PlutusDatumSchema.DetailedSchema);
-            }
-            else {
-                redeemerData = CSL.PlutusData.new_integer(CSL.BigInt.from_str(String(mintAction.redeemer ?? 0)));
-            }
+            const redeemerData = req.mintRedeemer
+                ? this._toPlutusData(req.mintRedeemer)
+                : CSL.PlutusData.new_integer(CSL.BigInt.from_str(String(mintAction.redeemer ?? 0)));
             const redeemer = CSL.Redeemer.new(CSL.RedeemerTag.new_mint(), CSL.BigNum.from_str('0'), redeemerData, CSL.ExUnits.new(CSL.BigNum.from_str(exUnits.mem), CSL.BigNum.from_str(exUnits.cpu)));
-            // Create MintWitness directly from PlutusScriptSource + Redeemer
             const mintWitness = CSL.MintWitness.new_plutus_script(scriptSource, redeemer);
-            // Add to mint builder
             mintBuilder.add_asset(mintWitness, cslAssetName, mintQuantity);
-            // Add to total minted value for output construction (only if quantity > 0)
             if (Number(mintAction.quantity) > 0) {
                 const assetValue = CSL.Value.new(CSL.BigNum.from_str('0'));
                 const multiAsset = CSL.MultiAsset.new();
@@ -441,43 +162,16 @@ class CSLTxBuilder {
                 totalMintedValue = totalMintedValue.checked_add(assetValue);
             }
         }
-        // Set the mint builder on transaction
         txb.set_mint_builder(mintBuilder);
-        // Add required signers if specified (for Plutus validators checking extra_signatories)
-        if (req.requiredSigners?.length) {
-            for (const signerHex of req.requiredSigners) {
-                txb.add_required_signer(CSL.Ed25519KeyHash.from_bytes(Buffer.from(signerHex, 'hex')));
-            }
-        }
+        this._addRequiredSigners(txb, req.requiredSigners);
         // Create output with minted assets + minimum lovelace
-        const minLovelace = CSL.BigNum.from_str(String(req.lovelaceAmount));
-        const outputValue = CSL.Value.new(minLovelace);
+        const outputValue = CSL.Value.new(CSL.BigNum.from_str(String(req.lovelaceAmount)));
         const finalOutputValue = outputValue.checked_add(totalMintedValue);
         const recipientOutput = CSL.TransactionOutput.new(recipientAddress, finalOutputValue);
-        if (req.inlineDatum) {
-            const datumData = CSL.PlutusData.from_json(JSON.stringify(req.inlineDatum), CSL.PlutusDatumSchema.DetailedSchema);
-            recipientOutput.set_plutus_data(datumData);
-        }
+        this._attachInlineDatum(recipientOutput, req.inlineDatum);
         txb.add_output(recipientOutput);
-        // Find an ADA-only UTxO for collateral
-        const collateralOdatanoUtxo = ctx.utxos.find(u => u.amount.every(a => a.unit.toLowerCase() === 'lovelace'));
-        if (collateralOdatanoUtxo) {
-            const collateralBuilder = CSL.TxInputsBuilder.new();
-            const txHash = CSL.TransactionHash.from_bytes(Buffer.from(collateralOdatanoUtxo.txHash, 'hex'));
-            const input = CSL.TransactionInput.new(txHash, collateralOdatanoUtxo.outputIndex);
-            const address = CSL.Address.from_bech32(collateralOdatanoUtxo.address);
-            const value = CSL.Value.new(CSL.BigNum.from_str((0, tx_build_helper_1.getLovelace)(collateralOdatanoUtxo).toString()));
-            collateralBuilder.add_regular_input(address, input, value);
-            txb.set_collateral(collateralBuilder);
-        }
-        // Exclude collateral UTxO so it is not consumed on successful tx.
-        let fundingUtxos = collateralOdatanoUtxo
-            ? ctx.utxos.filter(u => !(u.txHash === collateralOdatanoUtxo.txHash && u.outputIndex === collateralOdatanoUtxo.outputIndex))
-            : ctx.utxos;
-        if (fundingUtxos.length === 0 && ctx.utxos.length > 0) {
-            logger.debug('[CSLTxBuilder] No funding UTxOs after collateral exclusion, including collateral in funding pool');
-            fundingUtxos = ctx.utxos;
-        }
+        // Collateral + funding UTxO separation
+        const { fundingUtxos } = this._setupCollateral(txb, ctx.utxos);
         // Add all funding UTxOs as explicit inputs instead of using coin selection.
         // CSL's add_inputs_from does not properly forward native tokens from selected
         // inputs to the change output during Plutus minting transactions, causing
@@ -487,22 +181,7 @@ class CSLTxBuilder {
             const fTxHash = CSL.TransactionHash.from_bytes(Buffer.from(u.txHash, 'hex'));
             const fInput = CSL.TransactionInput.new(fTxHash, u.outputIndex);
             const fAddress = CSL.Address.from_bech32(u.address);
-            const fLovelace = CSL.BigNum.from_str((0, tx_build_helper_1.getLovelace)(u).toString());
-            const fValue = CSL.Value.new(fLovelace);
-            const fNonAdaAssets = u.amount.filter(a => a.unit.toLowerCase() !== 'lovelace' && BigInt(a.quantity) > 0n);
-            if (fNonAdaAssets.length > 0) {
-                const fMultiAsset = CSL.MultiAsset.new();
-                for (const asset of fNonAdaAssets) {
-                    const { policyId, assetName } = (0, tx_build_helper_1.parseAssetUnit)(asset.unit);
-                    const pH = CSL.ScriptHash.from_bytes(Buffer.from(policyId, 'hex'));
-                    let assets = fMultiAsset.get(pH);
-                    if (!assets)
-                        assets = CSL.Assets.new();
-                    assets.insert(CSL.AssetName.new(Buffer.from(assetName, 'hex')), CSL.BigNum.from_str(asset.quantity));
-                    fMultiAsset.insert(pH, assets);
-                }
-                fValue.set_multiasset(fMultiAsset);
-            }
+            const fValue = this._buildCslValue((0, tx_build_helper_1.getLovelace)(u), u.amount);
             fundingInputsBuilder.add_regular_input(fAddress, fInput, fValue);
         }
         txb.set_inputs(fundingInputsBuilder);
@@ -523,8 +202,7 @@ class CSLTxBuilder {
                 policy.set(an, (policy.get(an) || 0n) + BigInt(a.quantity));
             }
         }
-        // Adjust for burned tokens (negative mint quantities) — those tokens are
-        // destroyed, so the change output must not include them.
+        // Adjust for burned tokens (negative mint quantities)
         const scriptHashHex = Buffer.from(scriptHash.to_bytes()).toString('hex');
         for (const mintAction of req.mintActions) {
             const qty = BigInt(mintAction.quantity);
@@ -559,99 +237,26 @@ class CSLTxBuilder {
             const nativeChangeValue = CSL.Value.new(CSL.BigNum.from_str('2000000'));
             nativeChangeValue.set_multiasset(nativeChangeMA);
             txb.add_output(CSL.TransactionOutput.new(changeAddress, nativeChangeValue));
-            logger.debug('[CSLTxBuilder] Added explicit change output for existing native tokens from funding UTxOs');
+            logger.debug(`Added explicit change output for existing native tokens from funding UTxOs`);
         }
-        // Calculate script data hash BEFORE add_change_if_needed
-        // Always call calc_script_data_hash for Plutus transactions - CSL requires it
         const costModels = this._createCostModels('v3');
         txb.calc_script_data_hash(costModels);
-        // Now add change
         txb.add_change_if_needed(changeAddress);
-        // Build transaction and patch scriptDataHash (CSL's is incorrect for Conway PlutusV3)
         const tx = txb.build_tx();
         return this._patchScriptDataHash(tx);
     }
     async buildUnsignedPlutusSpendTransaction(req, ctx) {
         try {
-            // Determine execution units - default or from evaluator
-            let finalExUnits = {
-                mem: const_1.DEFAULT_EXECUTION_UNITS.mem.toString(),
-                cpu: const_1.DEFAULT_EXECUTION_UNITS.cpu.toString()
-            };
-            if (ctx.evaluateTransaction) {
-                // Build evaluation pass with high execution units
-                logger.debug(`[CSLTxBuilder] Building evaluation pass for Plutus spending`);
-                const highExUnits = {
-                    mem: const_1.HIGH_EXECUTION_UNITS.mem.toString(),
-                    cpu: const_1.HIGH_EXECUTION_UNITS.cpu.toString()
-                };
-                const evalTx = this._buildPlutusSpendTx(req, ctx, highExUnits);
-                const evalTxCbor = Buffer.from(evalTx.to_bytes()).toString('hex');
-                try {
-                    const evalResults = await ctx.evaluateTransaction(evalTxCbor);
-                    logger.debug(`[CSLTxBuilder] Evaluation results: ${JSON.stringify(evalResults)}`);
-                    if (evalResults && evalResults.length > 0) {
-                        const budget = evalResults[0].budget;
-                        finalExUnits = {
-                            mem: Math.ceil(budget.memory * const_1.EXECUTION_UNIT_BUFFER).toString(),
-                            cpu: Math.ceil(budget.cpu * const_1.EXECUTION_UNIT_BUFFER).toString()
-                        };
-                        logger.info(`[CSLTxBuilder] Using evaluated execution units: mem=${finalExUnits.mem}, cpu=${finalExUnits.cpu}`);
-                    }
-                }
-                catch (evalError) {
-                    logger.warn(`[CSLTxBuilder] Evaluation failed, using default units: ${evalError.message}`);
-                }
-            }
-            else {
-                logger.debug(`[CSLTxBuilder] No evaluator available, using default execution units`);
-            }
-            // Build final transaction with determined execution units
+            const finalExUnits = await this._evaluateExUnits((exUnits) => this._buildPlutusSpendTx(req, ctx, exUnits), ctx.evaluateTransaction);
             const unsignedTx = this._buildPlutusSpendTx(req, ctx, finalExUnits);
-            // Export as CBOR hex
-            const unsignedTxCbor = Buffer.from(unsignedTx.to_bytes()).toString('hex');
-            // Extract transaction details
-            const body = unsignedTx.body();
-            const bodyBytes = body.to_bytes();
-            const hash = (0, blake2b_1.default)(32).update(bodyBytes).digest('hex');
-            const txBodyHash = hash;
-            const feeLovelace = body.fee().to_str();
-            // Extract outputs
-            const outputs = [];
-            const txOuts = body.outputs();
-            for (let i = 0; i < txOuts.len(); i++) {
-                const o = txOuts.get(i);
-                outputs.push({
-                    address: o.address().to_bech32(),
-                    lovelace: o.amount().coin().to_str(),
-                });
-            }
-            // Compute script hash from the validator script
-            const spendScriptBytes = Buffer.from(req.plutusScriptExecution.validatorScript, 'hex');
-            const spendPlutusScript = CSL.PlutusScript.new_v3(spendScriptBytes);
-            const spendScriptHash = Buffer.from(spendPlutusScript.hash().to_bytes()).toString('hex');
-            logger.info(`[CSLTxBuilder] Built unsigned Plutus spending transaction. Fee: ${feeLovelace}`);
-            return {
-                unsignedTxCbor,
-                txBodyHash,
-                senderAddress: req.senderAddress,
-                network: this.cardanoClient.network,
-                sizeBytes: unsignedTxCbor.length / 2,
-                builderEngine: this.name,
-                feeLovelace,
-                inputs: ctx.utxos.map(u => ({
-                    txHash: u.txHash,
-                    index: u.outputIndex,
-                    lovelace: (0, tx_build_helper_1.getLovelace)(u).toString(),
-                })),
-                outputs,
-                scriptHash: spendScriptHash,
-                warnings: [],
-            };
+            const txDetails = this._extractTxDetails(unsignedTx);
+            const { hashHex: scriptHash } = this._computeScriptHash(req.plutusScriptExecution.validatorScript);
+            logger.info(`Built unsigned Plutus spending transaction. Fee: ${txDetails.feeLovelace}`);
+            return this._buildResult(req, ctx, txDetails, { scriptHash });
         }
         catch (error) {
-            logger.error(`[CSLTxBuilder] buildUnsignedPlutusSpendTransaction error: ${error?.message || error}`);
-            (0, tx_build_helper_1.mapBuilderError)(error, 'lovelace');
+            logger.error(`buildUnsignedPlutusSpendTransaction error: ${error?.message || error}`);
+            (0, tx_build_helper_1.mapBuilderError)(error);
         }
     }
     /**
@@ -660,17 +265,13 @@ class CSLTxBuilder {
     _buildPlutusSpendTx(req, ctx, exUnits) {
         const { plutusScriptExecution } = req;
         const scriptUtxoRef = plutusScriptExecution.scriptUtxo;
-        // Prepare addresses
         const recipientAddress = CSL.Address.from_bech32(req.recipientAddress);
         const changeAddress = CSL.Address.from_bech32(req.changeAddress ?? req.senderAddress);
-        // Create Transaction Builder
         const txb = CSL.TransactionBuilder.new(this.txBuilderConfig);
-        // Parse the Plutus validator script from CBOR hex (CBOR-wrapped flat UPLC bytecode)
-        const scriptBytes = Buffer.from(plutusScriptExecution.validatorScript, 'hex');
-        const plutusScript = CSL.PlutusScript.new_v3(scriptBytes);
+        const { plutusScript } = this._computeScriptHash(plutusScriptExecution.validatorScript);
         const scriptSource = CSL.PlutusScriptSource.new(plutusScript);
-        // Build redeemer (using DetailedSchema: { "constructor": 0, "fields": [] } format)
-        const redeemerPlutusData = CSL.PlutusData.from_json(JSON.stringify(plutusScriptExecution.redeemer), CSL.PlutusDatumSchema.DetailedSchema);
+        // Build redeemer
+        const redeemerPlutusData = this._toPlutusData(plutusScriptExecution.redeemer);
         const redeemer = CSL.Redeemer.new(CSL.RedeemerTag.new_spend(), CSL.BigNum.from_str('0'), // index will be corrected by CSL
         redeemerPlutusData, CSL.ExUnits.new(CSL.BigNum.from_str(exUnits.mem), CSL.BigNum.from_str(exUnits.cpu)));
         // Add the script input using TxInputsBuilder
@@ -680,100 +281,40 @@ class CSLTxBuilder {
         // Find the script UTxO to get its value
         const scriptOdatanoUtxo = ctx.utxos.find(u => u.txHash === scriptUtxoRef.txHash && u.outputIndex === scriptUtxoRef.outputIndex);
         if (!scriptOdatanoUtxo) {
-            throw new Error(`[CSLTxBuilder] Script UTxO ${scriptUtxoRef.txHash}#${scriptUtxoRef.outputIndex} not found in provided UTxOs`);
+            throw new Error(`Script UTxO ${scriptUtxoRef.txHash}#${scriptUtxoRef.outputIndex} not found in provided UTxOs`);
         }
-        // Build full multi-asset value for the script UTxO (lovelace + native assets)
-        const scriptUtxoValue = CSL.Value.new(CSL.BigNum.from_str((0, tx_build_helper_1.getLovelace)(scriptOdatanoUtxo).toString()));
         const scriptNonAdaAssets = scriptOdatanoUtxo.amount.filter(a => a.unit.toLowerCase() !== 'lovelace' && BigInt(a.quantity) > 0n);
-        if (scriptNonAdaAssets.length > 0) {
-            const scriptMultiAsset = CSL.MultiAsset.new();
-            for (const asset of scriptNonAdaAssets) {
-                const { policyId, assetName } = (0, tx_build_helper_1.parseAssetUnit)(asset.unit);
-                const policyHash = CSL.ScriptHash.from_bytes(Buffer.from(policyId, 'hex'));
-                let assets = scriptMultiAsset.get(policyHash);
-                if (!assets)
-                    assets = CSL.Assets.new();
-                assets.insert(CSL.AssetName.new(Buffer.from(assetName, 'hex')), CSL.BigNum.from_str(asset.quantity));
-                scriptMultiAsset.insert(policyHash, assets);
-            }
-            scriptUtxoValue.set_multiasset(scriptMultiAsset);
-        }
+        const scriptUtxoValue = this._buildCslValue((0, tx_build_helper_1.getLovelace)(scriptOdatanoUtxo), scriptOdatanoUtxo.amount);
         // Build PlutusWitness: datum handling depends on whether UTxO has inline datum
         let plutusWitness;
         if (plutusScriptExecution.datum) {
-            // Hash-based datum — add to witness set
-            const datumPlutusData = CSL.PlutusData.from_json(JSON.stringify(plutusScriptExecution.datum), CSL.PlutusDatumSchema.DetailedSchema);
-            const datumSource = CSL.DatumSource.new(datumPlutusData);
+            const datumSource = CSL.DatumSource.new(this._toPlutusData(plutusScriptExecution.datum));
             plutusWitness = CSL.PlutusWitness.new_with_ref(scriptSource, datumSource, redeemer);
         }
         else {
-            // Inline datum on UTxO — no datum witness needed
             plutusWitness = CSL.PlutusWitness.new_with_ref_without_datum(scriptSource, redeemer);
         }
-        // Add Plutus script input
         scriptInputsBuilder.add_plutus_script_input(plutusWitness, scriptInput, scriptUtxoValue);
         txb.set_inputs(scriptInputsBuilder);
-        // Add required signers if specified (for Plutus validators checking extra_signatories)
-        if (req.requiredSigners?.length) {
-            for (const signerHex of req.requiredSigners) {
-                txb.add_required_signer(CSL.Ed25519KeyHash.from_bytes(Buffer.from(signerHex, 'hex')));
-            }
-        }
+        this._addRequiredSigners(txb, req.requiredSigners);
         // Separate sender UTxOs (excluding script UTxO)
         const senderUtxos = ctx.utxos.filter(u => !(u.txHash === scriptUtxoRef.txHash && u.outputIndex === scriptUtxoRef.outputIndex));
-        // Find an ADA-only UTxO for collateral (from sender UTxOs only)
-        const collateralOdatanoUtxo = senderUtxos.find(u => u.amount.every(a => a.unit.toLowerCase() === 'lovelace'));
-        if (collateralOdatanoUtxo) {
-            const collateralBuilder = CSL.TxInputsBuilder.new();
-            const colTxHash = CSL.TransactionHash.from_bytes(Buffer.from(collateralOdatanoUtxo.txHash, 'hex'));
-            const colInput = CSL.TransactionInput.new(colTxHash, collateralOdatanoUtxo.outputIndex);
-            const colAddress = CSL.Address.from_bech32(collateralOdatanoUtxo.address);
-            const colValue = CSL.Value.new(CSL.BigNum.from_str((0, tx_build_helper_1.getLovelace)(collateralOdatanoUtxo).toString()));
-            collateralBuilder.add_regular_input(colAddress, colInput, colValue);
-            txb.set_collateral(collateralBuilder);
-        }
-        // Create output for recipient BEFORE coin selection so CSL knows the full
-        // output requirements (lovelace + assets + fee) when selecting funding UTxOs.
-        // Include multi-assets from the script UTxO in the continuing output.
+        // Collateral + funding UTxO separation (from sender UTxOs only)
+        const { fundingUtxos } = this._setupCollateral(txb, senderUtxos);
+        // Create output for recipient with multi-assets from the script UTxO
         const outputValue = CSL.Value.new(CSL.BigNum.from_str(String(req.lovelaceAmount || 2_000_000)));
         if (scriptNonAdaAssets.length > 0) {
-            const outputMultiAsset = CSL.MultiAsset.new();
-            for (const asset of scriptNonAdaAssets) {
-                const { policyId, assetName } = (0, tx_build_helper_1.parseAssetUnit)(asset.unit);
-                const policyHash = CSL.ScriptHash.from_bytes(Buffer.from(policyId, 'hex'));
-                let assets = outputMultiAsset.get(policyHash);
-                if (!assets)
-                    assets = CSL.Assets.new();
-                assets.insert(CSL.AssetName.new(Buffer.from(assetName, 'hex')), CSL.BigNum.from_str(asset.quantity));
-                outputMultiAsset.insert(policyHash, assets);
-            }
-            outputValue.set_multiasset(outputMultiAsset);
+            outputValue.set_multiasset(this._buildCslMultiAsset(scriptNonAdaAssets));
         }
         const recipientOutput = CSL.TransactionOutput.new(recipientAddress, outputValue);
-        if (req.inlineDatum) {
-            const datumData = CSL.PlutusData.from_json(JSON.stringify(req.inlineDatum), CSL.PlutusDatumSchema.DetailedSchema);
-            recipientOutput.set_plutus_data(datumData);
-        }
+        this._attachInlineDatum(recipientOutput, req.inlineDatum);
         txb.add_output(recipientOutput);
-        // Exclude collateral UTxO from coin selection so it is not consumed on successful tx.
-        // This preserves the dedicated collateral UTxO for future Plutus transactions.
-        // If no funding UTxOs remain after excluding collateral, fall back to including it —
-        // the same UTxO can appear in both inputs and collateral_inputs (consumed either way).
-        let fundingUtxos = collateralOdatanoUtxo
-            ? senderUtxos.filter(u => !(u.txHash === collateralOdatanoUtxo.txHash && u.outputIndex === collateralOdatanoUtxo.outputIndex))
-            : senderUtxos;
-        if (fundingUtxos.length === 0 && senderUtxos.length > 0) {
-            logger.debug('[CSLTxBuilder] No funding UTxOs after collateral exclusion, including collateral in funding pool');
-            fundingUtxos = senderUtxos;
-        }
+        // Coin selection from funding UTxOs
         const cslFundingUtxos = this._mapMultiAssetUtxosToCslUtxos(fundingUtxos);
         txb.add_inputs_from(cslFundingUtxos, CSL.CoinSelectionStrategyCIP2.LargestFirstMultiAsset);
-        // Calculate script data hash
         const costModels = this._createCostModels('v3');
         txb.calc_script_data_hash(costModels);
-        // Add change
         txb.add_change_if_needed(changeAddress);
-        // Build transaction and patch scriptDataHash (CSL's is incorrect for Conway PlutusV3)
         const tx = txb.build_tx();
         return this._patchScriptDataHash(tx);
     }
@@ -788,15 +329,11 @@ class CSLTxBuilder {
         const redeemers = witnesses.redeemers();
         if (!redeemers || redeemers.len() === 0)
             return tx;
-        // 1. Get redeemers CBOR from the built transaction
         const redeemersBytes = Buffer.from(redeemers.to_bytes());
-        // 2. Get datums CBOR if any (hash-based datums in witness set)
         const plutusData = witnesses.plutus_data();
         const datumsBytes = plutusData && plutusData.len() > 0
             ? Buffer.from(plutusData.to_bytes())
             : Buffer.alloc(0);
-        // 3. Compute correct language views using costModelsToLanguageViewCbor
-        //    Cost models are already correctly ordered by normalizeCostModels (uses toCostModelArrV3)
         const costModelsJson = JSON.parse(this.protocolParameters.costModels || '{}');
         const costModelsObj = {};
         const v3 = costModelsJson['plutus:v3'] || costModelsJson['PlutusV3'];
@@ -804,12 +341,10 @@ class CSLTxBuilder {
             costModelsObj.PlutusScriptV3 = Array.from((0, cardano_costmodels_ts_1.toCostModelArrV3)(v3)).map(Number);
         }
         const languageViews = Buffer.from((0, cardano_costmodels_ts_1.costModelsToLanguageViewCbor)(costModelsObj, { mustHaveV3: !!costModelsObj.PlutusScriptV3 }).toBuffer());
-        // 4. Compute: blake2b256(redeemers || datums || languageViews)
+        // blake2b256(redeemers || datums || languageViews)
         const hashInput = Buffer.concat([redeemersBytes, datumsBytes, languageViews]);
         const hashOutput = Buffer.alloc(32);
         (0, blake2b_1.default)(32).update(hashInput).digest(hashOutput);
-        // 5. Patch at raw byte level (CSL caches serialized bytes internally,
-        //    so set_script_data_hash + Transaction.new doesn't change the output)
         const wrongHash = tx.body().script_data_hash();
         if (!wrongHash)
             return tx;
@@ -825,47 +360,170 @@ class CSLTxBuilder {
         }
         hashOutput.copy(txBytes, idx);
         logger.info(`_patchScriptDataHash: patched ${wrongHashBytes.toString('hex').slice(0, 16)}... → ${hashOutput.toString('hex').slice(0, 16)}...`);
-        // 6. Reconstruct transaction from patched bytes
         return CSL.Transaction.from_bytes(txBytes);
     }
     //---------------------------------------------------------------------------
-    // Private Helper Methods
+    // Shared Helper Methods
+    //---------------------------------------------------------------------------
+    /** Convert JSON PlutusData to CSL PlutusData using DetailedSchema */
+    _toPlutusData(json) {
+        return CSL.PlutusData.from_json(JSON.stringify(json), CSL.PlutusDatumSchema.DetailedSchema);
+    }
+    /** Build CSL MultiAsset from an array of { unit, quantity } (skips lovelace entries) */
+    _buildCslMultiAsset(assets) {
+        const multiAsset = CSL.MultiAsset.new();
+        for (const asset of assets) {
+            if (asset.unit.toLowerCase() === 'lovelace')
+                continue;
+            const { policyId, assetName } = (0, tx_build_helper_1.parseAssetUnit)(asset.unit);
+            const policyHash = CSL.ScriptHash.from_bytes(Buffer.from(policyId, 'hex'));
+            let existing = multiAsset.get(policyHash);
+            if (!existing)
+                existing = CSL.Assets.new();
+            existing.insert(CSL.AssetName.new(Buffer.from(assetName, 'hex')), CSL.BigNum.from_str(asset.quantity));
+            multiAsset.insert(policyHash, existing);
+        }
+        return multiAsset;
+    }
+    /** Build CSL Value from lovelace + optional assets array */
+    _buildCslValue(lovelace, assets) {
+        const value = CSL.Value.new(CSL.BigNum.from_str(String(lovelace)));
+        const nonAda = assets?.filter(a => a.unit.toLowerCase() !== 'lovelace' && BigInt(a.quantity) > 0n);
+        if (nonAda && nonAda.length > 0) {
+            value.set_multiasset(this._buildCslMultiAsset(nonAda));
+        }
+        return value;
+    }
+    /** Extract CBOR, hash, fee, and outputs from a built CSL Transaction */
+    _extractTxDetails(unsignedTx) {
+        const unsignedTxCbor = Buffer.from(unsignedTx.to_bytes()).toString("hex");
+        const body = unsignedTx.body();
+        const txBodyHash = (0, blake2b_1.default)(32).update(body.to_bytes()).digest('hex');
+        const feeLovelace = body.fee().to_str();
+        const outputs = [];
+        const txOuts = body.outputs();
+        for (let i = 0; i < txOuts.len(); i++) {
+            const o = txOuts.get(i);
+            outputs.push({ address: o.address().to_bech32(), lovelace: o.amount().coin().to_str() });
+        }
+        return { unsignedTxCbor, txBodyHash, feeLovelace, outputs, sizeBytes: unsignedTxCbor.length / 2 };
+    }
+    /** Build the standard TxBuildResult object */
+    _buildResult(req, ctx, txDetails, extra) {
+        return {
+            unsignedTxCbor: txDetails.unsignedTxCbor,
+            txBodyHash: txDetails.txBodyHash,
+            senderAddress: req.senderAddress,
+            network: this.cardanoClient.network,
+            sizeBytes: txDetails.sizeBytes,
+            builderEngine: this.name,
+            feeLovelace: txDetails.feeLovelace,
+            inputs: ctx.utxos.map(u => ({
+                txHash: u.txHash,
+                index: u.outputIndex,
+                lovelace: (0, tx_build_helper_1.getLovelace)(u).toString(),
+            })),
+            outputs: txDetails.outputs,
+            ...extra,
+            warnings: [],
+        };
+    }
+    /** Add required signers (Ed25519 key hashes) to the transaction builder */
+    _addRequiredSigners(txb, signers) {
+        if (signers?.length) {
+            for (const signerHex of signers) {
+                txb.add_required_signer(CSL.Ed25519KeyHash.from_bytes(Buffer.from(signerHex, 'hex')));
+            }
+        }
+    }
+    /** Attach inline PlutusData datum to a transaction output */
+    _attachInlineDatum(output, datum) {
+        if (datum) {
+            output.set_plutus_data(this._toPlutusData(datum));
+        }
+    }
+    /** Parse PlutusV3 script hex and compute its hash */
+    _computeScriptHash(scriptHex) {
+        const plutusScript = CSL.PlutusScript.new_v3(Buffer.from(scriptHex, 'hex'));
+        const cslHash = plutusScript.hash();
+        return { plutusScript, hashHex: Buffer.from(cslHash.to_bytes()).toString('hex'), cslHash };
+    }
+    /**
+     * Evaluate execution units via a two-pass build: first with high units for evaluation,
+     * then apply the evaluated budget with a safety buffer. Falls back to defaults on failure.
+     */
+    async _evaluateExUnits(buildFn, evaluator) {
+        const defaultUnits = {
+            mem: String(const_1.DEFAULT_EXECUTION_UNITS.mem),
+            cpu: String(const_1.DEFAULT_EXECUTION_UNITS.cpu)
+        };
+        if (!evaluator) {
+            logger.debug('No evaluator available, using default execution units');
+            return defaultUnits;
+        }
+        logger.debug('Building evaluation pass with high execution units');
+        const evalTx = buildFn({
+            mem: String(const_1.HIGH_EXECUTION_UNITS.mem),
+            cpu: String(const_1.HIGH_EXECUTION_UNITS.cpu)
+        });
+        const evalTxCbor = Buffer.from(evalTx.to_bytes()).toString('hex');
+        try {
+            const evalResults = await evaluator(evalTxCbor);
+            logger.debug(`Evaluation results: ${JSON.stringify(evalResults)}`);
+            if (evalResults && evalResults.length > 0) {
+                const budget = evalResults[0].budget;
+                const result = {
+                    mem: Math.ceil(budget.memory * const_1.EXECUTION_UNIT_BUFFER).toString(),
+                    cpu: Math.ceil(budget.cpu * const_1.EXECUTION_UNIT_BUFFER).toString()
+                };
+                logger.info(`Using evaluated execution units: mem=${result.mem}, cpu=${result.cpu}`);
+                return result;
+            }
+        }
+        catch (evalError) {
+            logger.warn(`Evaluation failed, using default units: ${evalError.message}`);
+        }
+        return defaultUnits;
+    }
+    /**
+     * Find an ADA-only UTxO for collateral, set it on the builder,
+     * and return the remaining funding UTxOs with collateral excluded.
+     */
+    _setupCollateral(txb, utxos) {
+        const collateralUtxo = utxos.find(u => u.amount.every(a => a.unit.toLowerCase() === 'lovelace'));
+        if (collateralUtxo) {
+            const collateralBuilder = CSL.TxInputsBuilder.new();
+            const txHash = CSL.TransactionHash.from_bytes(Buffer.from(collateralUtxo.txHash, 'hex'));
+            const input = CSL.TransactionInput.new(txHash, collateralUtxo.outputIndex);
+            const address = CSL.Address.from_bech32(collateralUtxo.address);
+            const value = CSL.Value.new(CSL.BigNum.from_str((0, tx_build_helper_1.getLovelace)(collateralUtxo).toString()));
+            collateralBuilder.add_regular_input(address, input, value);
+            txb.set_collateral(collateralBuilder);
+        }
+        let fundingUtxos = collateralUtxo
+            ? utxos.filter(u => !(u.txHash === collateralUtxo.txHash && u.outputIndex === collateralUtxo.outputIndex))
+            : utxos;
+        if (fundingUtxos.length === 0 && utxos.length > 0) {
+            logger.debug('No funding UTxOs after collateral exclusion, including collateral in funding pool');
+            fundingUtxos = utxos;
+        }
+        return { collateralUtxo, fundingUtxos };
+    }
+    //---------------------------------------------------------------------------
+    // CSL Mapping & Configuration Helpers
     //---------------------------------------------------------------------------
     /**
      * Map ODATANO UTxOs to CSL TransactionUnspentOutputs (with multi-asset support)
-     * @param utxos ODATANO UTxO array
-     * @returns CSL TransactionUnspentOutputs
      */
     _mapMultiAssetUtxosToCslUtxos(utxos) {
         const outs = CSL.TransactionUnspentOutputs.new();
         logger.debug(`Mapping ${utxos.length} UTxOs to CSL format`);
         for (const u of utxos) {
             logger.debug(`UTxO ${u.txHash}:${u.outputIndex} has ${u.amount.length} amounts: ${JSON.stringify(u.amount)}`);
-            const txHashBytes = Buffer.from(u.txHash, "hex");
-            const txHash = CSL.TransactionHash.from_bytes(txHashBytes);
+            const txHash = CSL.TransactionHash.from_bytes(Buffer.from(u.txHash, "hex"));
             const input = CSL.TransactionInput.new(txHash, u.outputIndex);
             const addr = CSL.Address.from_bech32(u.address);
-            // Build value with ADA + all native assets
-            const lovelace = CSL.BigNum.from_str((0, tx_build_helper_1.getLovelace)(u).toString());
-            const value = CSL.Value.new(lovelace);
-            // Add native assets if any
-            const nonAdaAssets = u.amount.filter(a => a.unit.toLowerCase() !== 'lovelace' && BigInt(a.quantity) > 0n);
-            if (nonAdaAssets.length > 0) {
-                const multiAsset = CSL.MultiAsset.new();
-                for (const asset of nonAdaAssets) {
-                    const { policyId, assetName } = (0, tx_build_helper_1.parseAssetUnit)(asset.unit);
-                    const policyHash = CSL.ScriptHash.from_bytes(Buffer.from(policyId, 'hex'));
-                    let assets = multiAsset.get(policyHash);
-                    if (!assets) {
-                        assets = CSL.Assets.new();
-                    }
-                    const assetNameBytes = Buffer.from(assetName, 'hex');
-                    const assetNameObj = CSL.AssetName.new(assetNameBytes);
-                    assets.insert(assetNameObj, CSL.BigNum.from_str(asset.quantity));
-                    multiAsset.insert(policyHash, assets);
-                }
-                value.set_multiasset(multiAsset);
-            }
+            const value = this._buildCslValue((0, tx_build_helper_1.getLovelace)(u), u.amount);
             const output = CSL.TransactionOutput.new(addr, value);
             outs.add(CSL.TransactionUnspentOutput.new(input, output));
         }
@@ -873,12 +531,8 @@ class CSLTxBuilder {
     }
     /**
      * Create a CSL TransactionBuilderConfig from protocol parameters
-     * This config is created once and reused for all transactions
-     * @param protocolParams LedgerProtocolParameter
-     * @returns CSL.TransactionBuilderConfig
      */
     _createTxBuilderConfig(protocolParams) {
-        // required values for CSL config
         const minFeeA = protocolParams.minFeeA;
         const minFeeB = protocolParams.minFeeB;
         const poolDeposit = protocolParams.poolDeposit;
@@ -888,21 +542,15 @@ class CSLTxBuilder {
         const coinsPerUtxoByte = protocolParams.coinsPerUtxoSize;
         const feeAlgo = CSL.LinearFee.new(CSL.BigNum.from_str(String(minFeeA)), CSL.BigNum.from_str(String(minFeeB)));
         // Plutus execution unit prices for script fee calculation
-        // Protocol params may contain decimal prices (e.g., 0.0577) - convert to integer numerators
         const priceMemValue = protocolParams.priceMem;
         const priceStepValue = protocolParams.priceStep;
-        // Convert decimal prices to integer numerators (or use defaults if already integers or missing)
         const priceMemNumerator = (typeof priceMemValue === 'number' && priceMemValue < 1)
-            ? Math.round(priceMemValue * 10000) // 0.0577 -> 577
+            ? Math.round(priceMemValue * 10000)
             : (priceMemValue || 577);
         const priceStepNumerator = (typeof priceStepValue === 'number' && priceStepValue < 1)
-            ? Math.round(priceStepValue * 10000000) // 0.0000721 -> 721
+            ? Math.round(priceStepValue * 10000000)
             : (priceStepValue || 721);
-        const exUnitPrices = CSL.ExUnitPrices.new(CSL.UnitInterval.new(CSL.BigNum.from_str(String(priceMemNumerator)), // numerator
-        CSL.BigNum.from_str('10000') // denominator (0.0577 per memory unit)
-        ), CSL.UnitInterval.new(CSL.BigNum.from_str(String(priceStepNumerator)), // numerator
-        CSL.BigNum.from_str('10000000') // denominator (0.0000721 per CPU step)
-        ));
+        const exUnitPrices = CSL.ExUnitPrices.new(CSL.UnitInterval.new(CSL.BigNum.from_str(String(priceMemNumerator)), CSL.BigNum.from_str('10000')), CSL.UnitInterval.new(CSL.BigNum.from_str(String(priceStepNumerator)), CSL.BigNum.from_str('10000000')));
         const cfg = CSL.TransactionBuilderConfigBuilder.new()
             .fee_algo(feeAlgo)
             .pool_deposit(CSL.BigNum.from_str(String(poolDeposit)))
@@ -910,26 +558,21 @@ class CSLTxBuilder {
             .max_tx_size(Number(maxTxSize))
             .max_value_size(Number(maxValueSize))
             .coins_per_utxo_byte(CSL.BigNum.from_str(String(coinsPerUtxoByte)))
-            .ex_unit_prices(exUnitPrices) // Critical for Plutus fee calculation
+            .ex_unit_prices(exUnitPrices)
             .build();
         logger.info(`TransactionBuilderConfig created with Plutus execution unit prices.`);
         return cfg;
     }
     /**
      * Map ODATANO metadata JSON to CSL GeneralTransactionMetadata
-     * @param metadataJson JSON metadata object
-     * @returns CSL GeneralTransactionMetadata
      */
     _mapOdatanoMetadataToCSLMetadata(metadataJson) {
-        // Metadata must be an object with labels as keys
         if (typeof metadataJson !== 'object' || Array.isArray(metadataJson) || metadataJson === null) {
-            throw new Error(`[CSLTxBuilder] Invalid metadata format. Expected object, got ${typeof metadataJson}`);
+            throw new Error(`Invalid metadata format. Expected object, got ${typeof metadataJson}`);
         }
         const metadata = CSL.GeneralTransactionMetadata.new();
         for (const [label, value] of Object.entries(metadataJson)) {
-            // Convert label to BigNum
             const numericLabel = parseInt(label, 10);
-            // Convert JSON Value to CSL TransactionMetadatum
             const txMetadatum = this._jsonToCSLMetadatum(value);
             logger.debug(`Created TransactionMetadatum for label ${numericLabel}`);
             metadata.insert(CSL.BigNum.from_str(String(numericLabel)), txMetadatum);
@@ -939,15 +582,9 @@ class CSLTxBuilder {
     }
     /**
      * Create Costmdls from protocol parameters for specific Plutus version
-     * Required for correct script integrity hash calculation
-     * @param version - Optional: specific Plutus version ('v1', 'v2', 'v3'). If not provided, adds all versions.
-     * @returns CSL.Costmdls
      */
     _createCostModels(version) {
         const costModels = CSL.Costmdls.new();
-        // Blockfrost returns cost models as objects ({name: value}), CSL expects arrays.
-        // Convert object format to sorted-key array defensively (normalizeCostModels in mappers.ts
-        // already does this at the backend level, but handle it here too for robustness).
         const toArray = (costs) => {
             if (Array.isArray(costs))
                 return costs;
@@ -956,60 +593,42 @@ class CSLTxBuilder {
             }
             return null;
         };
+        const addCostModel = (language, costs, label) => {
+            const costModel = CSL.CostModel.new();
+            for (let i = 0; i < costs.length; i++) {
+                costModel.set(i, CSL.Int.new_i32(costs[i]));
+            }
+            costModels.insert(language, costModel);
+            logger.debug(`Added ${label} cost model with ${costs.length} parameters`);
+        };
         try {
-            // Parse cost models JSON from protocol parameters
-            // Format: { "plutus:v1": [array of 166 numbers], "plutus:v2": [array of 175 numbers], ... }
             const costModelsJson = JSON.parse(this.protocolParameters.costModels || '{}');
-            // PlutusV1 cost model
             if (!version || version === 'v1') {
-                const plutusV1Costs = toArray(costModelsJson['plutus:v1'] || costModelsJson['PlutusV1']);
-                if (plutusV1Costs) {
-                    const plutusV1CostModel = CSL.CostModel.new();
-                    for (let i = 0; i < plutusV1Costs.length; i++) {
-                        plutusV1CostModel.set(i, CSL.Int.new_i32(plutusV1Costs[i]));
-                    }
-                    costModels.insert(CSL.Language.new_plutus_v1(), plutusV1CostModel);
-                    logger.debug(`[CSLTxBuilder] Added PlutusV1 cost model with ${plutusV1Costs.length} parameters`);
-                }
+                const v1Costs = toArray(costModelsJson['plutus:v1'] || costModelsJson['PlutusV1']);
+                if (v1Costs)
+                    addCostModel(CSL.Language.new_plutus_v1(), v1Costs, 'PlutusV1');
             }
-            // PlutusV2 cost model
             if (!version || version === 'v2') {
-                const plutusV2Costs = toArray(costModelsJson['plutus:v2'] || costModelsJson['PlutusV2']);
-                if (plutusV2Costs) {
-                    const plutusV2CostModel = CSL.CostModel.new();
-                    for (let i = 0; i < plutusV2Costs.length; i++) {
-                        plutusV2CostModel.set(i, CSL.Int.new_i32(plutusV2Costs[i]));
-                    }
-                    costModels.insert(CSL.Language.new_plutus_v2(), plutusV2CostModel);
-                    logger.debug(`[CSLTxBuilder] Added PlutusV2 cost model with ${plutusV2Costs.length} parameters`);
-                }
+                const v2Costs = toArray(costModelsJson['plutus:v2'] || costModelsJson['PlutusV2']);
+                if (v2Costs)
+                    addCostModel(CSL.Language.new_plutus_v2(), v2Costs, 'PlutusV2');
             }
-            // PlutusV3 cost model (check both "plutus:v3" and "PlutusV3" formats)
             if (!version || version === 'v3') {
-                const plutusV3CostsRaw = toArray(costModelsJson['plutus:v3'] || costModelsJson['PlutusV3']);
-                if (plutusV3CostsRaw) {
-                    // Pad to 297 parameters (Conway Chang 2) using defaults from cardano-costmodels-ts.
-                    // Blockfrost may return only 251 (Chang 1). The node expects 297 for scriptDataHash.
-                    // toCostModelArrV3() fills missing params with default values — same as Buildooor.
-                    const plutusV3Costs = Array.from((0, cardano_costmodels_ts_1.toCostModelArrV3)(plutusV3CostsRaw)).map(Number);
-                    const plutusV3CostModel = CSL.CostModel.new();
-                    for (let i = 0; i < plutusV3Costs.length; i++) {
-                        plutusV3CostModel.set(i, CSL.Int.new_i32(plutusV3Costs[i]));
-                    }
-                    costModels.insert(CSL.Language.new_plutus_v3(), plutusV3CostModel);
-                    logger.debug(`[CSLTxBuilder] Added PlutusV3 cost model with ${plutusV3Costs.length} parameters`);
+                const v3CostsRaw = toArray(costModelsJson['plutus:v3'] || costModelsJson['PlutusV3']);
+                if (v3CostsRaw) {
+                    // Pad to 297 parameters (Conway Chang 2) using defaults from cardano-costmodels-ts
+                    const v3Costs = Array.from((0, cardano_costmodels_ts_1.toCostModelArrV3)(v3CostsRaw)).map(Number);
+                    addCostModel(CSL.Language.new_plutus_v3(), v3Costs, 'PlutusV3');
                 }
             }
         }
         catch (error) {
-            logger.warn(`[CSLTxBuilder] Failed to parse cost models: ${error}. Using empty cost models.`);
+            logger.warn(`Failed to parse cost models: ${error}. Using empty cost models.`);
         }
         return costModels;
     }
     /**
      * Convert JSON value to CSL TransactionMetadatum
-     * @param value JSON value
-     * @returns CSL TransactionMetadatum
      */
     _jsonToCSLMetadatum(value) {
         if (typeof value === 'number' || typeof value === 'bigint') {
@@ -1035,7 +654,7 @@ class CSLTxBuilder {
             }
             return CSL.TransactionMetadatum.new_map(map);
         }
-        throw new Error(`[CSLTxBuilder] Unsupported metadata value type: ${typeof value}`);
+        throw new Error(`Unsupported metadata value type: ${typeof value}`);
     }
 }
 exports.CSLTxBuilder = CSLTxBuilder;