@btc-vision/transaction 1.8.7-beta.0 → 1.8.8

package/build/epoch/validator/EpochValidator.d.ts

@@ -6,9 +6,31 @@ export declare class EpochValidator {
      */
     static sha1(data: Uint8Array): Uint8Array;
     /**
-     * Calculate mining preimage
+     * Calculate mining preimage.
+     *
+     * When useConcatenatedPreimage is false the legacy XOR construction is used
+     * (checksumRoot ^ publicKey ^ salt). That construction is malleable: a
+     * miner can set salt == publicKey to force preimage == checksumRoot (max
+     * difficulty for free), or transform any solution to another key via
+     * salt' = publicKey' ^ publicKey ^ salt. When useConcatenatedPreimage is true
+     * the preimage is the 96-byte concatenation checksumRoot || publicKey || salt,
+     * which removes both (the SHA-1 proof-of-work over it is unchanged).
+     *
+     * The switch is a consensus rule: callers pass useConcatenatedPreimage =
+     * (epochBlockHeight >= activationHeight) using the activation height for the
+     * network they are on (opnet-node exposes it as
+     * consensusEpochPatches.PREIMAGE_CONCAT_PATCH_BLOCK_HEIGHT). The value MUST be
+     * identical across opnet-node, this library and the mining pool.
      */
-    static calculatePreimage(checksumRoot: Uint8Array, publicKey: Uint8Array, salt: Uint8Array): Uint8Array;
+    static calculatePreimage(checksumRoot: Uint8Array, publicKey: Uint8Array, salt: Uint8Array, useConcatenatedPreimage?: boolean): Uint8Array;
+    /**
+     * Non-malleable mining preimage: the 96-byte concatenation
+     * checksumRoot || publicKey || salt. The public key sits in its own segment,
+     * so a miner-chosen salt can neither cancel it nor be transformed to
+     * re-attribute another miner's solution. The SHA-1 proof-of-work over it is
+     * unchanged.
+     */
+    static concatenatePreimage(checksumRoot: Uint8Array, publicKey: Uint8Array, salt: Uint8Array): Uint8Array;
     /**
      * Count matching bits between two hashes
      */
@@ -16,7 +38,7 @@ export declare class EpochValidator {
     /**
      * Verify an epoch solution using IPreimage
      */
-    static verifySolution(challenge: IChallengeSolution, log?: boolean): boolean;
+    static verifySolution(challenge: IChallengeSolution, log?: boolean, useHashedPreimage?: boolean): boolean;
     /**
      * Get the mining target block for an epoch
      */
@@ -24,11 +46,11 @@ export declare class EpochValidator {
     /**
      * Validate epoch winner from raw data
      */
-    static validateEpochWinner(epochData: RawChallenge): boolean;
+    static validateEpochWinner(epochData: RawChallenge, useHashedPreimage?: boolean): boolean;
     /**
      * Validate epoch winner from Preimage instance
      */
-    static validateChallengeSolution(challenge: IChallengeSolution): boolean;
+    static validateChallengeSolution(challenge: IChallengeSolution, useHashedPreimage?: boolean): boolean;
     /**
      * Calculate solution hash from preimage components
      * @param targetChecksum The target checksum (32 bytes)
@@ -36,7 +58,7 @@ export declare class EpochValidator {
      * @param salt The salt buffer (32 bytes)
      * @returns The SHA-1 hash of the preimage
      */
-    static calculateSolution(targetChecksum: Uint8Array, publicKey: Uint8Array, salt: Uint8Array): Uint8Array;
+    static calculateSolution(targetChecksum: Uint8Array, publicKey: Uint8Array, salt: Uint8Array, useHashedPreimage?: boolean): Uint8Array;
     /**
      * Check if a solution meets the minimum difficulty requirement
      */

package/build/epoch/validator/EpochValidator.js

@@ -10,13 +10,30 @@ export class EpochValidator {
         return crypto.sha1(data);
     }
     /**
-     * Calculate mining preimage
+     * Calculate mining preimage.
+     *
+     * When useConcatenatedPreimage is false the legacy XOR construction is used
+     * (checksumRoot ^ publicKey ^ salt). That construction is malleable: a
+     * miner can set salt == publicKey to force preimage == checksumRoot (max
+     * difficulty for free), or transform any solution to another key via
+     * salt' = publicKey' ^ publicKey ^ salt. When useConcatenatedPreimage is true
+     * the preimage is the 96-byte concatenation checksumRoot || publicKey || salt,
+     * which removes both (the SHA-1 proof-of-work over it is unchanged).
+     *
+     * The switch is a consensus rule: callers pass useConcatenatedPreimage =
+     * (epochBlockHeight >= activationHeight) using the activation height for the
+     * network they are on (opnet-node exposes it as
+     * consensusEpochPatches.PREIMAGE_CONCAT_PATCH_BLOCK_HEIGHT). The value MUST be
+     * identical across opnet-node, this library and the mining pool.
      */
-    static calculatePreimage(checksumRoot, publicKey, salt) {
+    static calculatePreimage(checksumRoot, publicKey, salt, useConcatenatedPreimage = false) {
         // Ensure all are 32 bytes
         if (checksumRoot.length !== 32 || publicKey.length !== 32 || salt.length !== 32) {
             throw new Error('All inputs must be 32 bytes');
         }
+        if (useConcatenatedPreimage) {
+            return this.concatenatePreimage(checksumRoot, publicKey, salt);
+        }
         const preimage = new Uint8Array(32);
         for (let i = 0; i < 32; i++) {
             preimage[i] =
@@ -24,6 +41,23 @@ export class EpochValidator {
         }
         return preimage;
     }
+    /**
+     * Non-malleable mining preimage: the 96-byte concatenation
+     * checksumRoot || publicKey || salt. The public key sits in its own segment,
+     * so a miner-chosen salt can neither cancel it nor be transformed to
+     * re-attribute another miner's solution. The SHA-1 proof-of-work over it is
+     * unchanged.
+     */
+    static concatenatePreimage(checksumRoot, publicKey, salt) {
+        if (checksumRoot.length !== 32 || publicKey.length !== 32 || salt.length !== 32) {
+            throw new Error('All inputs must be 32 bytes');
+        }
+        const message = new Uint8Array(96);
+        message.set(checksumRoot, 0);
+        message.set(publicKey, 32);
+        message.set(salt, 64);
+        return message;
+    }
     /**
      * Count matching bits between two hashes
      */
@@ -56,10 +90,10 @@ export class EpochValidator {
     /**
      * Verify an epoch solution using IPreimage
      */
-    static verifySolution(challenge, log = false) {
+    static verifySolution(challenge, log = false, useHashedPreimage = false) {
         try {
             const verification = challenge.verification;
-            const calculatedPreimage = this.calculatePreimage(verification.targetChecksum, challenge.publicKey.toBuffer(), challenge.salt);
+            const calculatedPreimage = this.calculatePreimage(verification.targetChecksum, challenge.publicKey.toBuffer(), challenge.salt, useHashedPreimage);
             const computedSolution = this.sha1(calculatedPreimage);
             if (!equals(computedSolution, challenge.solution)) {
                 return false;
@@ -92,7 +126,7 @@ export class EpochValidator {
     /**
      * Validate epoch winner from raw data
      */
-    static validateEpochWinner(epochData) {
+    static validateEpochWinner(epochData, useHashedPreimage = false) {
         try {
             const epochNumber = BigInt(epochData.epochNumber);
             const publicKey = Address.fromString(epochData.mldsaPublicKey, epochData.legacyPublicKey);
@@ -108,7 +142,7 @@ export class EpochValidator {
                 endBlock: BigInt(epochData.verification.endBlock),
                 proofs: Object.freeze(epochData.verification.proofs.map((p) => stringToBuffer(p))),
             };
-            const calculatedPreimage = this.calculatePreimage(verification.targetChecksum, publicKey.toBuffer(), salt);
+            const calculatedPreimage = this.calculatePreimage(verification.targetChecksum, publicKey.toBuffer(), salt, useHashedPreimage);
             const computedSolution = this.sha1(calculatedPreimage);
             if (!equals(computedSolution, solution)) {
                 return false;
@@ -129,8 +163,8 @@ export class EpochValidator {
     /**
      * Validate epoch winner from Preimage instance
      */
-    static validateChallengeSolution(challenge) {
-        return this.verifySolution(challenge);
+    static validateChallengeSolution(challenge, useHashedPreimage = false) {
+        return this.verifySolution(challenge, false, useHashedPreimage);
     }
     /**
      * Calculate solution hash from preimage components
@@ -139,8 +173,8 @@ export class EpochValidator {
      * @param salt The salt buffer (32 bytes)
      * @returns The SHA-1 hash of the preimage
      */
-    static calculateSolution(targetChecksum, publicKey, salt) {
-        const preimage = this.calculatePreimage(targetChecksum, publicKey, salt);
+    static calculateSolution(targetChecksum, publicKey, salt, useHashedPreimage = false) {
+        const preimage = this.calculatePreimage(targetChecksum, publicKey, salt, useHashedPreimage);
         return this.sha1(preimage);
     }
     /**

package/build/transaction/TransactionFactory.js

@@ -361,7 +361,7 @@ export class TransactionFactory {
             estimatedFees: resp.estimatedFees,
             tx: resp.tx.toHex(),
             nextUTXOs: this.getAllNewUTXOs(resp.original, resp.tx, parameters.from),
-            inputUtxos: parameters.utxos,
+            inputUtxos: [...parameters.utxos, ...(parameters.feeUtxos ?? [])],
         };
     }
     /**

package/build/transaction/builders/FundingTransaction.js

@@ -22,9 +22,12 @@ export class FundingTransaction extends TransactionBuilder {
             throw new Error('Recipient address is required');
         }
         this.addInputsFromUTXO();
-        // When autoAdjustAmount is enabled and the amount would leave no room for fees,
-        // estimate the fee first and reduce the output amount accordingly.
-        if (this.autoAdjustAmount && this.amount >= this.totalInputAmount) {
+        // When autoAdjustAmount is enabled, estimate the fee against the final
+        // transaction shape and reduce the output amount whenever amount + fee
+        // would exceed the total input. This covers both the send-max case
+        // (amount == totalInput) and the near-total case where amount alone fits
+        // but leaves no room for the requested feeRate.
+        if (this.autoAdjustAmount) {
             // Add temporary outputs matching the ACTUAL final transaction shape
             // so the fee estimate accounts for the real vsize.
             const numOutputs = this.splitInputsInto > 1 ? this.splitInputsInto : 1;
@@ -48,21 +51,25 @@ export class FundingTransaction extends TransactionBuilder {
                     });
                 }
             }
-            // If a note is present, add a temporary OP_RETURN since it affects vsize.
             if (this.note) {
                 this.addOPReturn(this.note);
             }
+            if (this.anchor) {
+                this.addAnchor();
+            }
             const estimatedFee = await this.estimateTransactionFees();
             // Remove all temporary outputs.
-            const tempCount = numOutputs + (this.note ? 1 : 0);
+            const tempCount = numOutputs + (this.note ? 1 : 0) + (this.anchor ? 1 : 0);
             for (let i = 0; i < tempCount; i++) {
                 this.outputs.pop();
             }
-            const adjustedAmount = this.totalInputAmount - estimatedFee;
-            if (adjustedAmount < TransactionBuilder.MINIMUM_DUST) {
-                throw new Error(`Insufficient funds: after deducting fee of ${estimatedFee} sats, remaining amount ${adjustedAmount} sats is below minimum dust`);
+            if (this.amount + estimatedFee > this.totalInputAmount) {
+                const adjustedAmount = this.totalInputAmount - estimatedFee;
+                if (adjustedAmount < TransactionBuilder.MINIMUM_DUST) {
+                    throw new Error(`Insufficient funds: after deducting fee of ${estimatedFee} sats, remaining amount ${adjustedAmount} sats is below minimum dust`);
+                }
+                this.amount = adjustedAmount;
             }
-            this.amount = adjustedAmount;
         }
         // Add the primary output(s) first
         if (this.splitInputsInto > 1) {
@@ -70,10 +77,7 @@ export class FundingTransaction extends TransactionBuilder {
         }
         else if (this.isPubKeyDestination) {
             const toHexClean = this.to.startsWith('0x') ? this.to.slice(2) : this.to;
-            const pubKeyScript = script.compile([
-                fromHex(toHexClean),
-                opcodes.OP_CHECKSIG,
-            ]);
+            const pubKeyScript = script.compile([fromHex(toHexClean), opcodes.OP_CHECKSIG]);
             this.addOutput({
                 value: toSatoshi(this.amount),
                 script: pubKeyScript,

package/build/transaction/builders/TransactionBuilder.d.ts

@@ -12,6 +12,7 @@ import { type Feature, Features } from '../../generators/Features.js';
 export declare const MINIMUM_AMOUNT_REWARD: bigint;
 export declare const MINIMUM_AMOUNT_CA: bigint;
 export declare const ANCHOR_SCRIPT: Uint8Array<ArrayBufferLike>;
+export declare const TOLERANCE = 1;
 /**
  * Allows to build a transaction like you would on Ethereum.
  * @description The transaction builder class

package/build/transaction/builders/TransactionBuilder.js

@@ -17,6 +17,10 @@ import { getLevelFromPublicKeyLength } from '../../generators/MLDSAData.js';
 export const MINIMUM_AMOUNT_REWARD = 330n; //540n;
 export const MINIMUM_AMOUNT_CA = 297n;
 export const ANCHOR_SCRIPT = fromHex('51024e73');
+// Tolerance for fees
+// Less than 1 is percentage: 0.10 equals +- 10%
+// 1 or more is satoshis, 5 equals +- 5 sat
+export const TOLERANCE = 1;
 /**
  * Allows to build a transaction like you would on Ethereum.
  * @description The transaction builder class
@@ -284,10 +288,23 @@ export class TransactionBuilder extends TweakedTransaction {
      * @throws {Error} - If something went wrong
      */
     async signPSBT() {
-        if (await this.signTransaction()) {
-            return this.transaction;
+        if (!this.utxos.length)
+            throw new Error('No UTXOs specified');
+        if (this.to &&
+            !this.isPubKeyDestination &&
+            !EcKeyPair.verifyContractAddress(this.to, this.network)) {
+            throw new Error('Invalid contract address. The contract address must be a taproot address.');
         }
-        throw new Error('Could not sign transaction');
+        if (this.signed)
+            throw new Error('Transaction is already signed');
+        this.signed = true;
+        await this.buildTransaction();
+        const built = await this.internalBuildTransaction(this.transaction);
+        if (!built)
+            throw new Error('Could not sign transaction');
+        if (this.regenerated)
+            throw new Error('Transaction was regenerated');
+        return this.transaction;
     }
     /**
      * Add an input to the transaction.
@@ -619,13 +636,21 @@ export class TransactionBuilder extends TweakedTransaction {
             if (this.debugFees) {
                 this.warn(`Amount to send back (${sendBackAmount} sat) is less than minimum dust. Fee without change: ${feeWithoutChange} sats`);
             }
-            if (this.totalInputAmount <= amountSpent) {
-                throw new Error(`Insufficient funds: need ${amountSpent + feeWithoutChange} sats but only have ${this.totalInputAmount} sats`);
-            }
             if (expectRefund && sendBackAmount < 0n) {
-                throw new Error(`Insufficient funds: need at least ${-sendBackAmount} more sats to cover fees.`);
+                throw new Error(`Insufficient funds for fee: need at least ${-sendBackAmount} more sats to cover fees.`);
             }
         }
+        const amountNeeded = amountSpent + this.transactionFee;
+        const tolerance = TOLERANCE < 1
+            ? BigInt(Math.ceil(Number(this.transactionFee) * TOLERANCE))
+            : BigInt(Math.ceil(TOLERANCE));
+        if (this.totalInputAmount < amountSpent) {
+            throw new Error(`Insufficient funds: need ${amountNeeded} sats but only have ${this.totalInputAmount} sats`);
+        }
+        if (this.totalInputAmount < amountNeeded - tolerance) {
+            const missingAmount = amountNeeded - this.totalInputAmount - tolerance;
+            throw new Error(`Insufficient funds for fee: need at least ${missingAmount} more sats to cover fees.`);
+        }
         if (this.debugFees) {
             this.log(`Final fee: ${this.transactionFee} sats, Change output: ${this.feeOutput ? `${this.feeOutput.value} sats` : 'none'}`);
         }

package/build/transaction/offline/OfflineTransactionManager.d.ts

@@ -5,6 +5,19 @@ import { TransactionBuilder } from '../builders/TransactionBuilder.js';
 import type { ISerializableTransactionState, PrecomputedData } from './interfaces/ISerializableState.js';
 import { type ReconstructionOptions } from './TransactionReconstructor.js';
 import type { IDeploymentParameters, IFundingTransactionParameters, IInteractionParameters, ITransactionParameters } from '../interfaces/ITransactionParameters.js';
+/**
+ * Per-input CSV multisig signing status.
+ */
+export interface CSVMultisigInputStatus {
+    /** PSBT input index */
+    readonly inputIndex: number;
+    /** Threshold required to spend this input */
+    readonly required: number;
+    /** Number of distinct cosigner signatures collected so far */
+    readonly collected: number;
+    /** Hex-encoded x-only pubkeys of the cosigners that have signed */
+    readonly signers: string[];
+}
 /**
  * Export options for offline transaction signing
  */
@@ -246,4 +259,41 @@ export declare class OfflineTransactionManager {
      * @returns Updated state
      */
     static multiSigUpdatePsbt(serializedState: string, psbtBase64: string): string;
+    /**
+     * Inspect collaborative signing progress on all CSV multisig inputs.
+     * Returns an empty array when no partial PSBT has been produced yet.
+     */
+    static csvMultisigGetStatus(serializedState: string): CSVMultisigInputStatus[];
+    /**
+     * Add the given signer's contribution to every CSV multisig input it can sign.
+     * No-op for inputs whose tapscript does not contain the signer's x-only pubkey.
+     *
+     * First call (no partial PSBT yet) builds the PSBT from the funding params
+     * using the provided signer as the builder's signer. Subsequent calls load
+     * the carried PSBT and add the signer's tapScriptSig where applicable.
+     */
+    static addCSVMultisigSignature(serializedState: string, signer: Signer | UniversalSigner): Promise<{
+        state: string;
+        final: boolean;
+        perInput: CSVMultisigInputStatus[];
+    }>;
+    /**
+     * Finalize every CSV multisig input on the partial PSBT and extract the
+     * raw transaction hex. Throws if any input is still below its threshold.
+     */
+    static csvMultisigFinalize(serializedState: string): string;
+    /**
+     * Sign every CSV multisig input whose tapscript contains the signer's
+     * x-only pubkey and does not yet carry a signature from that pubkey.
+     */
+    private static addSignerToCSVInputs;
+    /**
+     * Build per-input status for every CSV multisig input.
+     *
+     * Walks state.utxos so we can detect CSV multisig inputs even after the
+     * builder has already finalized them (which clears tapLeafScript). For
+     * partially-signed inputs the signers list reflects collected tapScriptSig
+     * entries; for finalized inputs collected is set to the threshold.
+     */
+    private static computeCSVMultisigStatus;
 }

package/build/transaction/offline/OfflineTransactionManager.js

@@ -1,4 +1,4 @@
-import { fromHex, Psbt, toHex } from '@btc-vision/bitcoin';
+import { fromHex, Psbt, toHex, toXOnly } from '@btc-vision/bitcoin';
 import {} from '@btc-vision/ecpair';
 import { TransactionType } from '../enums/TransactionType.js';
 import { TransactionBuilder } from '../builders/TransactionBuilder.js';
@@ -7,6 +7,7 @@ import { TransactionSerializer } from './TransactionSerializer.js';
 import { TransactionReconstructor, } from './TransactionReconstructor.js';
 import { TransactionStateCapture } from './TransactionStateCapture.js';
 import { isMultiSigSpecificData } from './interfaces/ITypeSpecificData.js';
+import { CSVMultisigProvider } from '../mineable/CSVMultisigProvider.js';
 /**
  * Main entry point for offline transaction signing workflow.
  *
@@ -435,4 +436,144 @@ export class OfflineTransactionManager {
         };
         return TransactionSerializer.toBase64(newState);
     }
+    /**
+     * Inspect collaborative signing progress on all CSV multisig inputs.
+     * Returns an empty array when no partial PSBT has been produced yet.
+     */
+    static csvMultisigGetStatus(serializedState) {
+        const state = TransactionSerializer.fromBase64(serializedState);
+        if (!state.partialPsbtBase64)
+            return [];
+        const network = TransactionReconstructor['nameToNetwork'](state.baseParams.networkName);
+        const psbt = Psbt.fromBase64(state.partialPsbtBase64, { network });
+        return this.computeCSVMultisigStatus(state, psbt, network);
+    }
+    /**
+     * Add the given signer's contribution to every CSV multisig input it can sign.
+     * No-op for inputs whose tapscript does not contain the signer's x-only pubkey.
+     *
+     * First call (no partial PSBT yet) builds the PSBT from the funding params
+     * using the provided signer as the builder's signer. Subsequent calls load
+     * the carried PSBT and add the signer's tapScriptSig where applicable.
+     */
+    static async addCSVMultisigSignature(serializedState, signer) {
+        const state = TransactionSerializer.fromBase64(serializedState);
+        const network = TransactionReconstructor['nameToNetwork'](state.baseParams.networkName);
+        let psbt;
+        if (state.partialPsbtBase64) {
+            psbt = Psbt.fromBase64(state.partialPsbtBase64, { network });
+            this.addSignerToCSVInputs(psbt, signer, network);
+        }
+        else {
+            const builder = this.importForSigning(serializedState, { signer });
+            psbt = await builder.signPSBT();
+            // Best-effort: ensure the signer's contribution is recorded on every
+            // CSV input where they're a cosigner (the builder already attempts
+            // this, but this guards against builds that bailed early).
+            this.addSignerToCSVInputs(psbt, signer, network);
+        }
+        const perInput = this.computeCSVMultisigStatus(state, psbt, network);
+        const final = perInput.length > 0 && perInput.every((s) => s.collected >= s.required);
+        const newState = {
+            ...state,
+            partialPsbtBase64: psbt.toBase64(),
+        };
+        return {
+            state: TransactionSerializer.toBase64(newState),
+            final,
+            perInput,
+        };
+    }
+    /**
+     * Finalize every CSV multisig input on the partial PSBT and extract the
+     * raw transaction hex. Throws if any input is still below its threshold.
+     */
+    static csvMultisigFinalize(serializedState) {
+        const state = TransactionSerializer.fromBase64(serializedState);
+        if (!state.partialPsbtBase64) {
+            throw new Error('No partial PSBT in state — call addCSVMultisigSignature first');
+        }
+        const network = TransactionReconstructor['nameToNetwork'](state.baseParams.networkName);
+        const psbt = Psbt.fromBase64(state.partialPsbtBase64, { network });
+        for (let i = 0; i < psbt.data.inputs.length; i++) {
+            const input = psbt.data.inputs[i];
+            if (!input.tapLeafScript || input.tapLeafScript.length === 0)
+                continue;
+            const leaf = input.tapLeafScript[0];
+            if (!leaf)
+                continue;
+            const addr = CSVMultisigProvider.deriveAddressFromTapscript(leaf.script, network);
+            if (!addr)
+                continue;
+            CSVMultisigProvider.finalizePsbtInput(psbt, i, network, addr);
+        }
+        return psbt.extractTransaction(true, true).toHex();
+    }
+    /**
+     * Sign every CSV multisig input whose tapscript contains the signer's
+     * x-only pubkey and does not yet carry a signature from that pubkey.
+     */
+    static addSignerToCSVInputs(psbt, signer, network) {
+        const signerXOnly = toXOnly(signer.publicKey);
+        const signerXOnlyHex = toHex(signerXOnly);
+        for (let i = 0; i < psbt.data.inputs.length; i++) {
+            const input = psbt.data.inputs[i];
+            if (!input.tapLeafScript || input.tapLeafScript.length === 0)
+                continue;
+            const leaf = input.tapLeafScript[0];
+            if (!leaf)
+                continue;
+            const addr = CSVMultisigProvider.deriveAddressFromTapscript(leaf.script, network);
+            if (!addr)
+                continue;
+            const isCosigner = addr.config.pubkeys.some((pk) => toHex(pk) === signerXOnlyHex);
+            if (!isCosigner)
+                continue;
+            const alreadySigned = (input.tapScriptSig ?? []).some((s) => toHex(s.pubkey) === signerXOnlyHex);
+            if (alreadySigned)
+                continue;
+            psbt.signTaprootInput(i, signer);
+        }
+    }
+    /**
+     * Build per-input status for every CSV multisig input.
+     *
+     * Walks state.utxos so we can detect CSV multisig inputs even after the
+     * builder has already finalized them (which clears tapLeafScript). For
+     * partially-signed inputs the signers list reflects collected tapScriptSig
+     * entries; for finalized inputs collected is set to the threshold.
+     */
+    static computeCSVMultisigStatus(state, psbt, network) {
+        const result = [];
+        for (let i = 0; i < state.utxos.length; i++) {
+            const utxo = state.utxos[i];
+            if (!utxo?.witnessScript)
+                continue;
+            const tapscript = fromHex(utxo.witnessScript);
+            const addr = CSVMultisigProvider.deriveAddressFromTapscript(tapscript, network);
+            if (!addr)
+                continue;
+            const input = psbt.data.inputs[i];
+            if (!input)
+                continue;
+            if (input.finalScriptWitness) {
+                // Already finalized — by construction it carried >= threshold sigs.
+                result.push({
+                    inputIndex: i,
+                    required: addr.config.threshold,
+                    collected: addr.config.threshold,
+                    signers: [],
+                });
+                continue;
+            }
+            const tapSigs = input.tapScriptSig ?? [];
+            result.push({
+                inputIndex: i,
+                required: addr.config.threshold,
+                collected: tapSigs.length,
+                signers: tapSigs.map((s) => toHex(s.pubkey)),
+            });
+        }
+        return result;
+    }
 }

package/build/transaction/offline/TransactionSerializer.js

@@ -35,6 +35,8 @@ export class TransactionSerializer {
         this.writeTypeSpecificData(writer, state.typeSpecificData);
         // Write precomputed data
         this.writePrecomputedData(writer, state.precomputedData);
+        // v2: partial PSBT (empty string when absent)
+        writer.writeStringWithLength(state.partialPsbtBase64 ?? '');
         // Get buffer and calculate checksum
         const dataBuffer = writer.getBuffer();
         const checksum = this.calculateChecksum(dataBuffer);
@@ -82,6 +84,12 @@ export class TransactionSerializer {
         const typeSpecificData = this.readTypeSpecificData(reader, header.transactionType);
         // Read precomputed data
         const precomputedData = this.readPrecomputedData(reader);
+        // v2+: partial PSBT (collaborative signing carryover)
+        let partialPsbtBase64;
+        if (header.formatVersion >= 2) {
+            const stored = reader.readStringWithLength();
+            partialPsbtBase64 = stored.length > 0 ? stored : undefined;
+        }
         return {
             header,
             baseParams,
@@ -92,6 +100,7 @@ export class TransactionSerializer {
             signerMappings,
             typeSpecificData,
             precomputedData,
+            ...(partialPsbtBase64 !== undefined ? { partialPsbtBase64 } : {}),
         };
     }
     /**

package/build/transaction/offline/interfaces/ISerializableState.d.ts

@@ -2,9 +2,10 @@ import { TransactionType } from '../../enums/TransactionType.js';
 import { ChainId } from '../../../network/ChainId.js';
 import type { TypeSpecificData } from './ITypeSpecificData.js';
 /**
- * Format version for serialization compatibility
+ * Format version for serialization compatibility.
+ * v2 adds the optional `partialPsbtBase64` field on the top-level state.
  */
-export declare const SERIALIZATION_FORMAT_VERSION = 1;
+export declare const SERIALIZATION_FORMAT_VERSION = 2;
 /**
  * Magic byte for identifying serialized transaction state
  */
@@ -129,4 +130,11 @@ export interface ISerializableTransactionState {
     readonly typeSpecificData: TypeSpecificData;
     /** Pre-computed data for deterministic rebuild */
     readonly precomputedData: PrecomputedData;
+    /**
+     * Partial PSBT (base64) carrying signatures collected so far.
+     * Used by collaborative flows like CSV multisig where multiple cosigners
+     * accumulate signatures across hops before finalization.
+     * Only present once at least one signing hop has run.
+     */
+    readonly partialPsbtBase64?: string;
 }

package/build/transaction/offline/interfaces/ISerializableState.js

@@ -1,9 +1,10 @@
 import { TransactionType } from '../../enums/TransactionType.js';
 import { ChainId } from '../../../network/ChainId.js';
 /**
- * Format version for serialization compatibility
+ * Format version for serialization compatibility.
+ * v2 adds the optional `partialPsbtBase64` field on the top-level state.
  */
-export const SERIALIZATION_FORMAT_VERSION = 1;
+export const SERIALIZATION_FORMAT_VERSION = 2;
 /**
  * Magic byte for identifying serialized transaction state
  */

package/build/transaction/shared/TweakedTransaction.js

@@ -580,10 +580,23 @@ export class TweakedTransaction extends Logger {
                 await this.signInputsSequential(transaction);
             }
         }
+        let allFinalized = true;
         for (let i = 0; i < transaction.data.inputs.length; i++) {
-            transaction.finalizeInput(i, this.customFinalizerP2SH.bind(this));
+            try {
+                transaction.finalizeInput(i, this.customFinalizerP2SH.bind(this));
+            }
+            catch (e) {
+                // CSV multisig inputs may legitimately be below threshold during
+                // a collaborative signing hop. Leave them unfinalized so the
+                // partial PSBT can travel to the next cosigner.
+                if (this.csvMultisigInputs.has(i)) {
+                    allFinalized = false;
+                    continue;
+                }
+                throw e;
+            }
         }
-        this.finalized = true;
+        this.finalized = allFinalized;
     }
     /**
      * Signs all inputs sequentially in batches of 20.
@@ -1155,11 +1168,20 @@ export class TweakedTransaction extends Logger {
         const signer = this.signer;
         // then, we sign all the remaining inputs with the wallet signer.
         await signer.multiSignPsbt([transaction]);
-        // Then, we finalize every input.
+        let allFinalized = true;
         for (let i = 0; i < transaction.data.inputs.length; i++) {
-            transaction.finalizeInput(i, this.customFinalizerP2SH.bind(this));
+            try {
+                transaction.finalizeInput(i, this.customFinalizerP2SH.bind(this));
+            }
+            catch (e) {
+                if (this.csvMultisigInputs.has(i)) {
+                    allFinalized = false;
+                    continue;
+                }
+                throw e;
+            }
         }
-        this.finalized = true;
+        this.finalized = allFinalized;
     }
     isCSVScript(decompiled) {
         return decompiled.some((op) => op === opcodes.OP_CHECKSEQUENCEVERIFY);