@odatano/core 0.3.16 → 0.3.18

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

@@ -31,207 +31,51 @@ class BuildooorTxBuilder {
         const params = protocolParams ?? await client.getProtocolParameters();
         const txbParameters = this._mapLedgerParametersToBuildooorParams(params);
         this.txBuilder = new buildooor_1.TxBuilder(txbParameters);
-        logger.debug(`TxBuilder initialized with protocol parameters`);
+        logger.debug(`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 {
-            // mapping of ODATANO UTxO Type to ledger-ts UTxO objects (with multi-asset support)
-            // This allows spending UTxOs that contain native assets - they will be returned in the change output
             const ledgerUtxos = ctx.utxos.map(utxo => this._mapMultiAssetUtxoToLedgerUtxo(utxo));
-            // and map to Buildooor TxIn objects for inputs
             const inputs = ledgerUtxos.map(utxo => ({ utxo }));
-            // set Addresses
             const recipientAddress = cardano_ledger_ts_1.Address.fromString(req.recipientAddress);
             const changeAddress = cardano_ledger_ts_1.Address.fromString(req.changeAddress ?? req.senderAddress);
-            // set Amount
             const amount = BigInt(String(req.lovelaceAmount));
-            // build new outputs for recipient (lovelace + optional native assets)
+            // Build output value (lovelace + optional native assets)
             let outputValue = cardano_ledger_ts_1.Value.lovelaces(amount);
             if (req.assets && req.assets.length > 0) {
-                for (const asset of req.assets) {
-                    if (asset.unit === 'lovelace')
-                        continue;
-                    const { policyId, assetName } = (0, tx_build_helper_1.parseAssetUnit)(asset.unit);
-                    const assetValue = cardano_ledger_ts_1.Value.singleAsset(new cardano_ledger_ts_1.Hash28(policyId), Buffer.from(assetName, 'hex'), BigInt(asset.quantity));
-                    outputValue = cardano_ledger_ts_1.Value.add(outputValue, assetValue);
-                }
-            }
-            const txOutParams = {
-                address: recipientAddress,
-                value: outputValue,
-            };
-            if (req.outputDatum) {
-                txOutParams.datum = (0, tx_build_helper_1.jsonToPlutusData)(req.outputDatum);
+                outputValue = this._buildLedgerValue(amount, req.assets);
             }
-            const outputs = [new cardano_ledger_ts_1.TxOut(txOutParams)];
-            // build the transaction
-            const tx = await this.txBuilder.build({
-                inputs,
-                outputs,
-                changeAddress,
-            });
-            // full unsigned tx cbor (4-tuple, witness empty)
-            const unsignedTxBytes = tx.toCbor().toBuffer();
-            const unsignedTxCbor = (0, uint8array_utils_1.toHex)(unsignedTxBytes);
-            const txBodyHash = tx.hash.toString();
+            const outputs = [this._buildTxOut(recipientAddress, outputValue, req.outputDatum)];
+            const tx = await this.txBuilder.build({ inputs, outputs, changeAddress });
             logger.debug(`Built unsigned transaction successfully.`);
-            return {
-                unsignedTxCbor: unsignedTxCbor,
-                txBodyHash: txBodyHash,
-                senderAddress: req.senderAddress,
-                network: this.cardanoClient.network,
-                sizeBytes: unsignedTxBytes.length,
-                builderEngine: this.name,
-                feeLovelace: tx.body.fee.toString(),
-                inputs: ctx.utxos.map(u => ({
-                    txHash: u.txHash,
-                    index: u.outputIndex,
-                    lovelace: (0, tx_build_helper_1.getLovelace)(u).toString()
-                })),
-                outputs: tx.body.outputs.map((o) => ({
-                    address: o.address?.toString?.() ?? "",
-                    lovelace: o.value?.lovelaces?.toString?.() ?? "0"
-                })),
-                warnings: []
-            };
+            return this._buildResult(req, ctx, this._extractTxDetails(tx));
         }
         catch (err) {
-            (0, tx_build_helper_1.mapBuilderError)(err, 'lovelace');
+            (0, tx_build_helper_1.mapBuilderError)(err);
         }
     }
     async buildUnsignedTransactionWithMetadata(req, ctx) {
         try {
-            // mapping of ODATANO UTxO Type to ledger-ts UTxO objects (with multi-asset support)
-            // This allows spending UTxOs that contain native assets - they will be returned in the change output
             const ledgerUtxos = ctx.utxos.map(utxo => this._mapMultiAssetUtxoToLedgerUtxo(utxo));
-            // Buildooor TxIn objects for inputs
             const inputs = ledgerUtxos.map(utxo => ({ utxo }));
-            // Addresses
             const recipientAddress = cardano_ledger_ts_1.Address.fromString(req.recipientAddress);
             const changeAddress = cardano_ledger_ts_1.Address.fromString(req.changeAddress ?? req.senderAddress);
-            // Amount
             const amount = BigInt(String(req.lovelaceAmount));
             const metadata = this._mapOdatanoMetadataToLedgerMetadata(req.metadataJson);
-            // build new outputs for recipient
-            const outputs = [
-                new cardano_ledger_ts_1.TxOut({
-                    address: recipientAddress,
-                    value: cardano_ledger_ts_1.Value.lovelaces(amount)
-                })
-            ];
-            // build the transaction
-            const tx = await this.txBuilder.build({
-                inputs,
-                outputs,
-                changeAddress,
-                metadata
-            });
-            // full unsigned tx cbor (4-tuple, witness empty)
-            const unsignedTxBytes = tx.toCbor().toBuffer();
-            const unsignedTxCbor = (0, uint8array_utils_1.toHex)(unsignedTxBytes);
-            const txBodyHash = tx.hash.toString();
+            const outputs = [new cardano_ledger_ts_1.TxOut({ address: recipientAddress, value: cardano_ledger_ts_1.Value.lovelaces(amount) })];
+            const tx = await this.txBuilder.build({ inputs, outputs, changeAddress, metadata });
             logger.debug(`Built unsigned transaction successfully.`);
-            return {
-                unsignedTxCbor: unsignedTxCbor,
-                txBodyHash: txBodyHash,
-                senderAddress: req.senderAddress,
-                network: this.cardanoClient.network,
-                builderEngine: this.name,
-                sizeBytes: unsignedTxBytes.length,
-                feeLovelace: tx.body.fee.toString(),
-                inputs: ctx.utxos.map(u => ({
-                    txHash: u.txHash,
-                    index: u.outputIndex,
-                    lovelace: (0, tx_build_helper_1.getLovelace)(u).toString()
-                })),
-                outputs: tx.body.outputs.map((o) => ({
-                    address: o.address?.toString?.() ?? "",
-                    lovelace: o.value?.lovelaces?.toString?.() ?? "0"
-                })),
-                warnings: []
-            };
+            return this._buildResult(req, ctx, this._extractTxDetails(tx));
         }
         catch (err) {
-            (0, tx_build_helper_1.mapBuilderError)(err, 'lovelace');
-        }
-    }
-    async buildUnsignedMultiAssetTransaction(req, ctx) {
-        if (!req.assets || req.assets.length === 0) {
-            throw new Error('[BuildooorTxBuilder] buildUnsignedMultiAssetTransaction requires assets to be specified');
-        }
-        try {
-            // Map all available UTxOs to ledger UTxOs for Buildooor (let builder handle selection)
-            const ledgerUtxos = ctx.utxos.map(utxo => this._mapMultiAssetUtxoToLedgerUtxo(utxo));
-            // Buildooor TxIn objects for inputs
-            const inputs = ledgerUtxos.map(utxo => ({ utxo }));
-            // Addresses
-            const recipientAddress = cardano_ledger_ts_1.Address.fromString(req.recipientAddress);
-            const changeAddress = cardano_ledger_ts_1.Address.fromString(req.changeAddress ?? req.senderAddress);
-            // Build output value with ADA + assets
-            let outputValue = cardano_ledger_ts_1.Value.lovelaces(BigInt(req.lovelaceAmount));
-            for (const asset of req.assets) {
-                // Parse policyId and assetName from unit (format: policyId.assetName or policyId+assetName)
-                const { policyId, assetName } = (0, tx_build_helper_1.parseAssetUnit)(asset.unit);
-                const policyHash = new cardano_ledger_ts_1.Hash28(policyId);
-                const assetValue = cardano_ledger_ts_1.Value.singleAsset(policyHash, Buffer.from(assetName, 'hex'), BigInt(asset.quantity));
-                outputValue = cardano_ledger_ts_1.Value.add(outputValue, assetValue);
-            }
-            // Build output (with optional inline datum for script addresses)
-            const txOutParams = {
-                address: recipientAddress,
-                value: outputValue,
-            };
-            if (req.outputDatum) {
-                txOutParams.datum = (0, tx_build_helper_1.jsonToPlutusData)(req.outputDatum);
-            }
-            const outputs = [new cardano_ledger_ts_1.TxOut(txOutParams)];
-            // Build the transaction
-            const tx = await this.txBuilder.build({
-                inputs,
-                outputs,
-                changeAddress,
-            });
-            // Full unsigned tx cbor (4-tuple, witness empty)
-            const unsignedTxBytes = tx.toCbor().toBuffer();
-            const unsignedTxCbor = (0, uint8array_utils_1.toHex)(unsignedTxBytes);
-            const txBodyHash = tx.hash.toString();
-            logger.debug(`Built unsigned multi-asset transaction successfully.`);
-            return {
-                unsignedTxCbor: unsignedTxCbor,
-                txBodyHash: txBodyHash,
-                senderAddress: req.senderAddress,
-                network: this.cardanoClient.network,
-                sizeBytes: unsignedTxBytes.length,
-                builderEngine: this.name,
-                feeLovelace: tx.body.fee.toString(),
-                inputs: ctx.utxos.map(u => ({
-                    txHash: u.txHash,
-                    index: u.outputIndex,
-                    lovelace: (0, tx_build_helper_1.getLovelace)(u).toString()
-                })),
-                outputs: tx.body.outputs.map((o) => ({
-                    address: o.address?.toString?.() ?? "",
-                    lovelace: o.value?.lovelaces?.toString?.() ?? "0"
-                })),
-                warnings: []
-            };
-        }
-        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];
-            (0, tx_build_helper_1.mapBuilderError)(err, assetUnit);
+            (0, tx_build_helper_1.mapBuilderError)(err);
         }
     }
     async buildUnsignedMintTransaction(req, ctx) {
         try {
-            // Addresses
             const recipientAddress = cardano_ledger_ts_1.Address.fromString(req.recipientAddress);
             const changeAddress = cardano_ledger_ts_1.Address.fromString(req.changeAddress ?? req.senderAddress);
             // Parse the minting policy script once
@@ -242,9 +86,8 @@ class BuildooorTxBuilder {
                 const mints = [];
                 for (const mintAction of req.mintActions) {
                     const { assetName } = (0, tx_build_helper_1.parseAssetUnit)(mintAction.assetUnit);
-                    const assetValue = cardano_ledger_ts_1.Value.singleAsset(script.hash, Buffer.from(assetName, 'hex'), BigInt(mintAction.quantity));
                     mints.push({
-                        value: assetValue,
+                        value: cardano_ledger_ts_1.Value.singleAsset(script.hash, Buffer.from(assetName, 'hex'), BigInt(mintAction.quantity)),
                         script: {
                             inline: script,
                             redeemer: req.mintRedeemer
@@ -262,126 +105,36 @@ class BuildooorTxBuilder {
                 const quantity = BigInt(mintAction.quantity);
                 if (quantity > 0n) {
                     const { assetName } = (0, tx_build_helper_1.parseAssetUnit)(mintAction.assetUnit);
-                    const assetValue = cardano_ledger_ts_1.Value.singleAsset(script.hash, Buffer.from(assetName, 'hex'), quantity);
-                    mintValue = cardano_ledger_ts_1.Value.add(mintValue, assetValue);
+                    mintValue = cardano_ledger_ts_1.Value.add(mintValue, cardano_ledger_ts_1.Value.singleAsset(script.hash, Buffer.from(assetName, 'hex'), quantity));
                 }
             }
-            // Build output value - recipient gets the minted assets + min ADA
-            let outputValue = cardano_ledger_ts_1.Value.lovelaces(BigInt(req.lovelaceAmount || 1_000_000));
+            // Build output — recipient gets the minted assets + min ADA
+            let outputValue = cardano_ledger_ts_1.Value.lovelaces(BigInt(req.lovelaceAmount));
             outputValue = cardano_ledger_ts_1.Value.add(outputValue, mintValue);
-            // Build output
-            const txOutParams = {
-                address: recipientAddress,
-                value: outputValue,
-            };
-            if (req.inlineDatum) {
-                txOutParams.datum = (0, tx_build_helper_1.jsonToPlutusData)(req.inlineDatum);
-            }
-            const outputs = [new cardano_ledger_ts_1.TxOut(txOutParams)];
-            // Find an ADA-only UTxO for collateral (Plutus scripts require ADA-only collateral)
-            const adaOnlyUtxo = ctx.utxos.find(u => u.amount.every(a => a.unit.toLowerCase() === 'lovelace'));
-            if (!adaOnlyUtxo) {
-                throw new Error('[BuildooorTxBuilder] No ADA-only UTxO available for collateral. Plutus scripts require ADA-only collateral.');
-            }
-            // Use only 1 collateral to minimize tx size
-            const collateralUtxos = [this._mapOdatanoUtxoToLedgerUtxo(adaOnlyUtxo)];
-            // Exclude collateral UTxO from regular inputs so it is not consumed on successful tx.
-            // This preserves the dedicated collateral UTxO for future Plutus transactions.
-            const fundingUtxos = ctx.utxos.filter(u => !(u.txHash === adaOnlyUtxo.txHash && u.outputIndex === adaOnlyUtxo.outputIndex));
+            const outputs = [this._buildTxOut(recipientAddress, outputValue, req.inlineDatum)];
+            // Collateral + funding separation
+            const { collateralUtxos, fundingUtxos } = this._setupCollateral(ctx.utxos);
             const fundingLedgerUtxos = fundingUtxos.map(utxo => this._mapMultiAssetUtxoToLedgerUtxo(utxo));
             const inputs = fundingLedgerUtxos.map(utxo => ({ utxo }));
-            // Determine execution units based on evaluator availability
-            let finalExUnits = const_1.DEFAULT_EXECUTION_UNITS;
-            if (ctx.evaluateTransaction) {
-                // Build first pass with high execution units for evaluation
-                logger.debug(`Building evaluation pass with high execution units`);
-                const evalMints = buildMints(const_1.HIGH_EXECUTION_UNITS);
+            // Evaluate execution units
+            const finalExUnits = await this._evaluateExUnits(async () => {
                 const evalTx = await this.txBuilder.build({
-                    inputs,
-                    outputs,
-                    changeAddress,
-                    mints: evalMints,
-                    collaterals: collateralUtxos,
-                    requiredSigners: req.requiredSigners
+                    inputs, outputs, changeAddress, mints: buildMints(const_1.HIGH_EXECUTION_UNITS),
+                    collaterals: collateralUtxos, requiredSigners: req.requiredSigners
                 });
-                const evalTxCbor = (0, uint8array_utils_1.toHex)(evalTx.toCbor().toBuffer());
-                try {
-                    // Evaluate to get exact execution units
-                    const evalResults = await ctx.evaluateTransaction(evalTxCbor);
-                    logger.debug(`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),
-                            cpu: Math.ceil(budget.cpu * const_1.EXECUTION_UNIT_BUFFER)
-                        };
-                        logger.info(`Using evaluated execution units: mem=${finalExUnits.mem}, cpu=${finalExUnits.cpu}`);
-                    }
-                }
-                catch (evalError) {
-                    logger.warn(`Evaluation failed, using default units: ${evalError.message}`);
-                    // Fall back to defaults on evaluation failure
-                }
-            }
-            else {
-                logger.debug(`No evaluator available, using default execution units`);
-            }
-            // Build with final execution units
+                return (0, uint8array_utils_1.toHex)(evalTx.toCbor().toBuffer());
+            }, ctx.evaluateTransaction);
+            // Build with final execution units + witness buffer
             const mints = buildMints(finalExUnits);
-            // First build to calculate base fee
-            const txFirstPass = await this.txBuilder.build({
-                inputs,
-                outputs,
-                changeAddress,
-                mints: mints,
-                collaterals: collateralUtxos,
-                requiredSigners: req.requiredSigners
-            });
-            // Add minimal buffer for witness set CBOR overhead (signing adds ~44 bytes)
-            const calculatedFee = BigInt(txFirstPass.body.fee.toString());
-            const witnessBuffer = BigInt(const_1.WITNESS_BUFFER_BYTES);
-            const adjustedMinFee = calculatedFee + witnessBuffer;
-            logger.debug(`First pass fee: ${calculatedFee}, rebuilding with witness buffer: ${adjustedMinFee}`);
-            // Final build with adjusted minimum fee to account for witness overhead
-            const tx = await this.txBuilder.build({
-                inputs,
-                outputs,
-                changeAddress,
-                mints: mints,
-                collaterals: collateralUtxos,
-                requiredSigners: req.requiredSigners,
-                fee: adjustedMinFee
+            const tx = await this._buildWithWitnessBuffer({
+                inputs, outputs, changeAddress, mints,
+                collaterals: collateralUtxos, requiredSigners: req.requiredSigners
             });
-            // Full unsigned tx cbor (4-tuple, witness empty)
-            const unsignedTxBytes = tx.toCbor().toBuffer();
-            const unsignedTxCbor = (0, uint8array_utils_1.toHex)(unsignedTxBytes);
-            const txBodyHash = tx.hash.toString();
             logger.debug(`Built unsigned minting transaction successfully with fee: ${tx.body.fee.toString()}`);
-            return {
-                unsignedTxCbor: unsignedTxCbor,
-                txBodyHash: txBodyHash,
-                senderAddress: req.senderAddress,
-                network: this.cardanoClient.network,
-                builderEngine: this.name,
-                sizeBytes: unsignedTxBytes.length,
-                feeLovelace: tx.body.fee.toString(),
-                inputs: ctx.utxos.map(u => ({
-                    txHash: u.txHash,
-                    index: u.outputIndex,
-                    lovelace: (0, tx_build_helper_1.getLovelace)(u).toString()
-                })),
-                outputs: tx.body.outputs.map((o) => ({
-                    address: o.address?.toString?.() ?? "",
-                    lovelace: o.value?.lovelaces?.toString?.() ?? "0"
-                })),
-                scriptHash: script.hash.toString(),
-                warnings: []
-            };
+            return this._buildResult(req, ctx, this._extractTxDetails(tx), { scriptHash: script.hash.toString() });
         }
         catch (err) {
-            (0, tx_build_helper_1.mapBuilderError)(err, 'lovelace');
+            (0, tx_build_helper_1.mapBuilderError)(err);
         }
     }
     async buildUnsignedPlutusSpendTransaction(req, ctx) {
@@ -397,160 +150,173 @@ class BuildooorTxBuilder {
                 ? (0, tx_build_helper_1.jsonToPlutusData)(plutusScriptExecution.datum)
                 : "inline";
             // Find the specific script UTxO in the provided context UTxOs
-            // The coordinator is responsible for including the script UTxO in ctx.utxos
             const scriptUtxoRef = plutusScriptExecution.scriptUtxo;
             const scriptOdatanoUtxo = ctx.utxos.find(u => u.txHash === scriptUtxoRef.txHash && u.outputIndex === scriptUtxoRef.outputIndex);
             if (!scriptOdatanoUtxo) {
-                throw new Error(`[BuildooorTxBuilder] 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`);
             }
-            // Map the script UTxO to ledger format
             const scriptLedgerUtxo = this._mapMultiAssetUtxoToLedgerUtxo(scriptOdatanoUtxo);
             // Map sender UTxOs (excluding the script UTxO) as regular inputs
             const senderUtxos = ctx.utxos.filter(u => !(u.txHash === scriptUtxoRef.txHash && u.outputIndex === scriptUtxoRef.outputIndex));
-            // Addresses
             const recipientAddress = cardano_ledger_ts_1.Address.fromString(req.recipientAddress);
             const changeAddress = cardano_ledger_ts_1.Address.fromString(req.changeAddress ?? req.senderAddress);
             // Build output — include multi-assets from script UTxO in continuing output
+            const scriptNonAdaAssets = scriptOdatanoUtxo.amount.filter(a => a.unit.toLowerCase() !== 'lovelace' && BigInt(a.quantity) > 0n);
             let outputValue = cardano_ledger_ts_1.Value.lovelaces(BigInt(req.lovelaceAmount || 2_000_000));
-            for (const amount of scriptOdatanoUtxo.amount) {
-                if (amount.unit.toLowerCase() !== 'lovelace' && BigInt(amount.quantity) > 0n) {
-                    const { policyId, assetName } = (0, tx_build_helper_1.parseAssetUnit)(amount.unit);
-                    const policyHash = new cardano_ledger_ts_1.Hash28(policyId);
-                    const assetValue = cardano_ledger_ts_1.Value.singleAsset(policyHash, Buffer.from(assetName, 'hex'), BigInt(amount.quantity));
-                    outputValue = cardano_ledger_ts_1.Value.add(outputValue, assetValue);
-                }
+            if (scriptNonAdaAssets.length > 0) {
+                outputValue = this._buildLedgerValue(BigInt(req.lovelaceAmount || 2_000_000), scriptOdatanoUtxo.amount);
             }
-            const txOutParams = {
-                address: recipientAddress,
-                value: outputValue,
-            };
-            if (req.inlineDatum) {
-                txOutParams.datum = (0, tx_build_helper_1.jsonToPlutusData)(req.inlineDatum);
-            }
-            const outputs = [new cardano_ledger_ts_1.TxOut(txOutParams)];
-            // Find an ADA-only UTxO for collateral (from sender UTxOs only)
-            const adaOnlyUtxo = senderUtxos.find(u => u.amount.every(a => a.unit.toLowerCase() === 'lovelace'));
-            if (!adaOnlyUtxo) {
-                throw new Error('[BuildooorTxBuilder] No ADA-only UTxO available for collateral. Plutus scripts require ADA-only collateral.');
-            }
-            const collateralUtxos = [this._mapOdatanoUtxoToLedgerUtxo(adaOnlyUtxo)];
-            // Exclude collateral UTxO from regular inputs so it is not consumed on successful tx.
-            // This preserves the dedicated collateral UTxO for future Plutus transactions.
-            const fundingUtxos = senderUtxos.filter(u => !(u.txHash === adaOnlyUtxo.txHash && u.outputIndex === adaOnlyUtxo.outputIndex));
+            const outputs = [this._buildTxOut(recipientAddress, outputValue, req.inlineDatum)];
+            // Collateral + funding separation (from sender UTxOs only)
+            const { collateralUtxos, fundingUtxos } = this._setupCollateral(senderUtxos);
             const fundingLedgerUtxos = fundingUtxos.map(utxo => this._mapMultiAssetUtxoToLedgerUtxo(utxo));
             // Helper to build inputs with specified execution units
             const buildInputs = (exUnits) => {
-                // Script input with witness
                 const scriptInput = {
                     utxo: scriptLedgerUtxo,
-                    inputScript: {
-                        script,
-                        datum,
-                        redeemer: redeemerData,
-                        executionUnits: exUnits
-                    }
+                    inputScript: { script, datum, redeemer: redeemerData, executionUnits: exUnits }
                 };
-                // Regular sender inputs for fees (excluding collateral)
                 const regularInputs = fundingLedgerUtxos.map(utxo => ({ utxo }));
                 return [scriptInput, ...regularInputs];
             };
-            // Determine execution units based on evaluator availability
-            let finalExUnits = const_1.DEFAULT_EXECUTION_UNITS;
-            if (ctx.evaluateTransaction) {
-                // Build first pass with high execution units for evaluation
-                logger.debug(`Building evaluation pass with high execution units`);
-                const evalInputs = buildInputs(const_1.HIGH_EXECUTION_UNITS);
+            // Evaluate execution units
+            const finalExUnits = await this._evaluateExUnits(async () => {
                 const evalTx = await this.txBuilder.build({
-                    inputs: evalInputs,
-                    outputs,
-                    changeAddress,
-                    collaterals: collateralUtxos,
-                    requiredSigners: req.requiredSigners
+                    inputs: buildInputs(const_1.HIGH_EXECUTION_UNITS), outputs, changeAddress,
+                    collaterals: collateralUtxos, requiredSigners: req.requiredSigners
                 });
-                const evalTxCbor = (0, uint8array_utils_1.toHex)(evalTx.toCbor().toBuffer());
-                try {
-                    const evalResults = await ctx.evaluateTransaction(evalTxCbor);
-                    logger.debug(`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),
-                            cpu: Math.ceil(budget.cpu * const_1.EXECUTION_UNIT_BUFFER)
-                        };
-                        logger.info(`Using evaluated execution units: mem=${finalExUnits.mem}, cpu=${finalExUnits.cpu}`);
-                    }
-                }
-                catch (evalError) {
-                    logger.warn(`Evaluation failed, using default units: ${evalError.message}`);
-                }
-            }
-            else {
-                logger.debug(`No evaluator available, using default execution units`);
-            }
-            // Build with final execution units
+                return (0, uint8array_utils_1.toHex)(evalTx.toCbor().toBuffer());
+            }, ctx.evaluateTransaction);
+            // Build with final execution units + witness buffer
             const inputs = buildInputs(finalExUnits);
-            // First build to calculate base fee
-            const txFirstPass = await this.txBuilder.build({
-                inputs,
-                outputs,
-                changeAddress,
-                collaterals: collateralUtxos,
-                requiredSigners: req.requiredSigners
+            const tx = await this._buildWithWitnessBuffer({
+                inputs, outputs, changeAddress,
+                collaterals: collateralUtxos, requiredSigners: req.requiredSigners
             });
-            // Add minimal buffer for witness set CBOR overhead
-            const calculatedFee = BigInt(txFirstPass.body.fee.toString());
-            const witnessBuffer = BigInt(const_1.WITNESS_BUFFER_BYTES);
-            const adjustedMinFee = calculatedFee + witnessBuffer;
-            logger.debug(`First pass fee: ${calculatedFee}, rebuilding with witness buffer: ${adjustedMinFee}`);
-            // Final build with adjusted minimum fee
-            const tx = await this.txBuilder.build({
-                inputs,
-                outputs,
-                changeAddress,
-                collaterals: collateralUtxos,
-                requiredSigners: req.requiredSigners,
-                fee: adjustedMinFee
-            });
-            const unsignedTxBytes = tx.toCbor().toBuffer();
-            const unsignedTxCbor = (0, uint8array_utils_1.toHex)(unsignedTxBytes);
-            const txBodyHash = tx.hash.toString();
             logger.debug(`Built unsigned Plutus spending transaction successfully with fee: ${tx.body.fee.toString()}`);
-            return {
-                unsignedTxCbor,
-                txBodyHash,
-                senderAddress: req.senderAddress,
-                network: this.cardanoClient.network,
-                builderEngine: this.name,
-                sizeBytes: unsignedTxBytes.length,
-                feeLovelace: tx.body.fee.toString(),
-                inputs: ctx.utxos.map(u => ({
-                    txHash: u.txHash,
-                    index: u.outputIndex,
-                    lovelace: (0, tx_build_helper_1.getLovelace)(u).toString()
-                })),
-                outputs: tx.body.outputs.map((o) => ({
-                    address: o.address?.toString?.() ?? "",
-                    lovelace: o.value?.lovelaces?.toString?.() ?? "0"
-                })),
-                scriptHash: script.hash.toString(),
-                warnings: []
-            };
+            return this._buildResult(req, ctx, this._extractTxDetails(tx), { scriptHash: script.hash.toString() });
         }
         catch (err) {
-            (0, tx_build_helper_1.mapBuilderError)(err, 'lovelace');
+            (0, tx_build_helper_1.mapBuilderError)(err);
+        }
+    }
+    //---------------------------------------------------------------------------
+    // Shared Helper Methods
+    //---------------------------------------------------------------------------
+    /** Extract CBOR, hash, fee, size, and outputs from a built Buildooor Tx */
+    _extractTxDetails(tx) {
+        const unsignedTxBytes = tx.toCbor().toBuffer();
+        return {
+            unsignedTxCbor: (0, uint8array_utils_1.toHex)(unsignedTxBytes),
+            txBodyHash: tx.hash.toString(),
+            sizeBytes: unsignedTxBytes.length,
+            feeLovelace: tx.body.fee.toString(),
+            outputDetails: tx.body.outputs.map((o) => ({
+                address: o.address?.toString?.() ?? "",
+                lovelace: o.value?.lovelaces?.toString?.() ?? "0"
+            })),
+        };
+    }
+    /** Build the standard TxBuildResult object */
+    _buildResult(req, ctx, txDetails, extra) {
+        return {
+            unsignedTxCbor: txDetails.unsignedTxCbor,
+            txBodyHash: txDetails.txBodyHash,
+            senderAddress: req.senderAddress,
+            network: this.cardanoClient.network,
+            builderEngine: this.name,
+            sizeBytes: txDetails.sizeBytes,
+            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.outputDetails,
+            ...extra,
+            warnings: [],
+        };
+    }
+    /**
+     * Evaluate execution units via callback. Caller provides an async function
+     * that builds the evaluation tx and returns its CBOR hex.
+     */
+    async _evaluateExUnits(buildEvalTx, evaluator) {
+        if (!evaluator) {
+            logger.debug('No evaluator available, using default execution units');
+            return const_1.DEFAULT_EXECUTION_UNITS;
+        }
+        logger.debug('Building evaluation pass with high execution units');
+        const evalTxCbor = await buildEvalTx();
+        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),
+                    cpu: Math.ceil(budget.cpu * const_1.EXECUTION_UNIT_BUFFER)
+                };
+                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 const_1.DEFAULT_EXECUTION_UNITS;
+    }
+    /** Two-pass build: first build to calculate fee, then rebuild with witness buffer */
+    async _buildWithWitnessBuffer(buildParams) {
+        const txFirstPass = await this.txBuilder.build(buildParams);
+        const calculatedFee = BigInt(txFirstPass.body.fee.toString());
+        const adjustedMinFee = calculatedFee + BigInt(const_1.WITNESS_BUFFER_BYTES);
+        logger.debug(`First pass fee: ${calculatedFee}, rebuilding with witness buffer: ${adjustedMinFee}`);
+        return this.txBuilder.build({ ...buildParams, fee: adjustedMinFee });
+    }
+    /**
+     * Find an ADA-only UTxO for collateral, map it, and return remaining funding UTxOs.
+     * Throws if no ADA-only UTxO is available.
+     */
+    _setupCollateral(utxos) {
+        const adaOnlyUtxo = utxos.find(u => u.amount.every(a => a.unit.toLowerCase() === 'lovelace'));
+        if (!adaOnlyUtxo) {
+            throw new Error('No ADA-only UTxO available for collateral. Plutus scripts require ADA-only collateral.');
         }
+        const collateralUtxos = [this._mapOdatanoUtxoToLedgerUtxo(adaOnlyUtxo)];
+        const fundingUtxos = utxos.filter(u => !(u.txHash === adaOnlyUtxo.txHash && u.outputIndex === adaOnlyUtxo.outputIndex));
+        return { collateralUtxos, fundingUtxos };
+    }
+    /** Build a Ledger Value from lovelace + optional multi-asset array */
+    _buildLedgerValue(lovelace, assets) {
+        let value = cardano_ledger_ts_1.Value.lovelaces(lovelace);
+        if (assets) {
+            for (const asset of assets) {
+                if (asset.unit.toLowerCase() === 'lovelace')
+                    continue;
+                if (BigInt(asset.quantity) <= 0n)
+                    continue;
+                const { policyId, assetName } = (0, tx_build_helper_1.parseAssetUnit)(asset.unit);
+                value = cardano_ledger_ts_1.Value.add(value, cardano_ledger_ts_1.Value.singleAsset(new cardano_ledger_ts_1.Hash28(policyId), Buffer.from(assetName, 'hex'), BigInt(asset.quantity)));
+            }
+        }
+        return value;
+    }
+    /** Build a TxOut with optional inline datum */
+    _buildTxOut(address, value, datum) {
+        const params = { address, value };
+        if (datum) {
+            params.datum = (0, tx_build_helper_1.jsonToPlutusData)(datum);
+        }
+        return new cardano_ledger_ts_1.TxOut(params);
     }
     //---------------------------------------------------------------------------
-    // Private Helper Methods
+    // UTxO Mapping & Configuration Helpers
     //---------------------------------------------------------------------------
     /**
      * Map ODATANO LedgerProtocolParameter to Buildooor's ProtocolParameters shape
-     * @param protocolParameters ledger protocol parameters
-     * @returns mapped protocol parameters
      */
     _mapLedgerParametersToBuildooorParams(protocolParameters) {
-        // Map LedgerProtocolParameter to Buildooor's ProtocolParameters shape
-        // Using defaultProtocolParameters as base and overriding with actual values
         return {
             ...cardano_ledger_ts_1.defaultProtocolParameters,
             txFeePerByte: Number(protocolParameters.minFeeA),
@@ -564,22 +330,14 @@ class BuildooorTxBuilder {
     }
     /**
      * Map ODATANO UTxO to Ledger UTxO (ADA-only)
-     * @param utxos ODATANO UTxO
-     * @returns mapped Ledger UTxO
      */
     _mapOdatanoUtxoToLedgerUtxo(utxos) {
         (0, tx_build_helper_1.assertAdaOnly)(utxos);
-        const outRef = new cardano_ledger_ts_1.TxOutRef({
-            id: utxos.txHash,
-            index: utxos.outputIndex
-        });
-        const addr = cardano_ledger_ts_1.Address.fromString(utxos.address);
-        const value = cardano_ledger_ts_1.Value.lovelaces((0, tx_build_helper_1.getLovelace)(utxos));
         return new cardano_ledger_ts_1.UTxO({
-            utxoRef: outRef,
+            utxoRef: new cardano_ledger_ts_1.TxOutRef({ id: utxos.txHash, index: utxos.outputIndex }),
             resolved: new cardano_ledger_ts_1.TxOut({
-                address: addr,
-                value,
+                address: cardano_ledger_ts_1.Address.fromString(utxos.address),
+                value: cardano_ledger_ts_1.Value.lovelaces((0, tx_build_helper_1.getLovelace)(utxos)),
                 datum: undefined,
                 refScript: undefined
             })
@@ -587,32 +345,14 @@ class BuildooorTxBuilder {
     }
     /**
      * Map ODATANO UTxO to Ledger UTxO (with multi-asset support)
-     * @param utxo ODATANO UTxO
-     * @returns mapped Ledger UTxO
      */
     _mapMultiAssetUtxoToLedgerUtxo(utxo) {
-        const outRef = new cardano_ledger_ts_1.TxOutRef({
-            id: utxo.txHash,
-            index: utxo.outputIndex
-        });
-        const addr = cardano_ledger_ts_1.Address.fromString(utxo.address);
-        // Build Value from all amounts
-        let value = cardano_ledger_ts_1.Value.lovelaces((0, tx_build_helper_1.getLovelace)(utxo));
-        for (const amount of utxo.amount) {
-            if (amount.unit.toLowerCase() !== 'lovelace') {
-                const { policyId, assetName } = (0, tx_build_helper_1.parseAssetUnit)(amount.unit);
-                const policyHash = new cardano_ledger_ts_1.Hash28(policyId);
-                const assetValue = cardano_ledger_ts_1.Value.singleAsset(policyHash, Buffer.from(assetName, 'hex'), BigInt(amount.quantity));
-                value = cardano_ledger_ts_1.Value.add(value, assetValue);
-            }
-        }
-        const datumValue = utxo.inlineDatum
-            ? (0, plutus_data_1.dataFromCbor)(utxo.inlineDatum)
-            : undefined;
+        const value = this._buildLedgerValue((0, tx_build_helper_1.getLovelace)(utxo), utxo.amount);
+        const datumValue = utxo.inlineDatum ? (0, plutus_data_1.dataFromCbor)(utxo.inlineDatum) : undefined;
         return new cardano_ledger_ts_1.UTxO({
-            utxoRef: outRef,
+            utxoRef: new cardano_ledger_ts_1.TxOutRef({ id: utxo.txHash, index: utxo.outputIndex }),
             resolved: new cardano_ledger_ts_1.TxOut({
-                address: addr,
+                address: cardano_ledger_ts_1.Address.fromString(utxo.address),
                 value,
                 datum: datumValue,
                 refScript: undefined
@@ -621,8 +361,6 @@ class BuildooorTxBuilder {
     }
     /**
      * Map ODATANO metadata JSON to Ledger TxMetadata
-     * @param metadataJson  metadata in JSON format
-     * @returns mapped TxMetadata
      */
     _mapOdatanoMetadataToLedgerMetadata(metadataJson) {
         if (!metadataJson) {
@@ -630,9 +368,7 @@ class BuildooorTxBuilder {
         }
         const metadata = {};
         for (const [label, value] of Object.entries(metadataJson)) {
-            // convert label to number
             const numericLabel = parseInt(label, 10);
-            // convert JSON value to TxMetadatum
             const txMetadatum = this._jsonToTxMetadatum(value);
             logger.debug(`Created TxMetadatum for label ${numericLabel}: ${txMetadatum.constructor.name}`);
             metadata[numericLabel] = txMetadatum;
@@ -644,8 +380,6 @@ class BuildooorTxBuilder {
     }
     /**
      * Recursively convert JSON value to TxMetadatum
-     * @param value JSON value
-     * @returns corresponding TxMetadatum
      */
     _jsonToTxMetadatum(value) {
         if (typeof value === 'number' || typeof value === 'bigint') {
@@ -667,7 +401,7 @@ class BuildooorTxBuilder {
             }
             return new TxMetadatum_1.TxMetadatumMap(map);
         }
-        throw new Error(`[BuildooorTxBuilder] Unsupported metadata value type: ${typeof value}`);
+        throw new Error(`Unsupported metadata value type: ${typeof value}`);
     }
 }
 exports.BuildooorTxBuilder = BuildooorTxBuilder;