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

package/src/transaction/offline/OfflineTransactionManager.ts

@@ -1,4 +1,4 @@
-import { fromHex, Psbt, type PsbtInput, type Signer, toHex } from '@btc-vision/bitcoin';
+import { fromHex, Psbt, type PsbtInput, type Signer, toHex, toXOnly } from '@btc-vision/bitcoin';
 import { type UniversalSigner } from '@btc-vision/ecpair';
 import { TransactionType } from '../enums/TransactionType.js';
 import { TransactionBuilder } from '../builders/TransactionBuilder.js';
@@ -14,6 +14,21 @@ import type {
     IInteractionParameters,
     ITransactionParameters,
 } from '../interfaces/ITransactionParameters.js';
+import { CSVMultisigProvider } from '../mineable/CSVMultisigProvider.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
@@ -626,4 +641,179 @@ 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.
+     */
+    public static csvMultisigGetStatus(serializedState: string): CSVMultisigInputStatus[] {
+        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.
+     */
+    public static async addCSVMultisigSignature(
+        serializedState: string,
+        signer: Signer | UniversalSigner,
+    ): Promise<{
+        state: string;
+        final: boolean;
+        perInput: CSVMultisigInputStatus[];
+    }> {
+        const state = TransactionSerializer.fromBase64(serializedState);
+        const network = TransactionReconstructor['nameToNetwork'](state.baseParams.networkName);
+
+        let psbt: 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: ISerializableTransactionState = {
+            ...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.
+     */
+    public static csvMultisigFinalize(serializedState: string): string {
+        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] as PsbtInput;
+            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.
+     */
+    private static addSignerToCSVInputs(
+        psbt: Psbt,
+        signer: Signer | UniversalSigner,
+        network: import('@btc-vision/bitcoin').Network,
+    ): void {
+        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] as PsbtInput;
+            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 as Uint8Array) === 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.
+     */
+    private static computeCSVMultisigStatus(
+        state: ISerializableTransactionState,
+        psbt: Psbt,
+        network: import('@btc-vision/bitcoin').Network,
+    ): CSVMultisigInputStatus[] {
+        const result: CSVMultisigInputStatus[] = [];
+
+        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] as PsbtInput | undefined;
+            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/src/transaction/offline/TransactionSerializer.ts

@@ -67,6 +67,9 @@ export class TransactionSerializer {
         // 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);
@@ -128,6 +131,13 @@ export class TransactionSerializer {
         // Read precomputed data
         const precomputedData = this.readPrecomputedData(reader);
 
+        // v2+: partial PSBT (collaborative signing carryover)
+        let partialPsbtBase64: string | undefined;
+        if (header.formatVersion >= 2) {
+            const stored = reader.readStringWithLength();
+            partialPsbtBase64 = stored.length > 0 ? stored : undefined;
+        }
+
         return {
             header,
             baseParams,
@@ -138,6 +148,7 @@ export class TransactionSerializer {
             signerMappings,
             typeSpecificData,
             precomputedData,
+            ...(partialPsbtBase64 !== undefined ? { partialPsbtBase64 } : {}),
         };
     }
 

package/src/transaction/offline/interfaces/ISerializableState.ts

@@ -3,9 +3,10 @@ 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 const SERIALIZATION_FORMAT_VERSION = 1;
+export const SERIALIZATION_FORMAT_VERSION = 2;
 
 /**
  * Magic byte for identifying serialized transaction state
@@ -138,4 +139,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/src/transaction/shared/TweakedTransaction.ts

@@ -769,11 +769,27 @@ export abstract class TweakedTransaction extends Logger implements Disposable {
             }
         }
 
+        let allFinalized = true;
         for (let i = 0; i < transaction.data.inputs.length; i++) {
-            transaction.finalizeInput(i, this.customFinalizerP2SH.bind(this) as FinalScriptsFunc);
+            try {
+                transaction.finalizeInput(
+                    i,
+                    this.customFinalizerP2SH.bind(this) as FinalScriptsFunc,
+                );
+            } 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;
     }
 
     /**
@@ -1509,12 +1525,24 @@ export abstract class TweakedTransaction extends Logger implements Disposable {
         // 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) as FinalScriptsFunc);
+            try {
+                transaction.finalizeInput(
+                    i,
+                    this.customFinalizerP2SH.bind(this) as FinalScriptsFunc,
+                );
+            } catch (e) {
+                if (this.csvMultisigInputs.has(i)) {
+                    allFinalized = false;
+                    continue;
+                }
+
+                throw e;
+            }
         }
 
-        this.finalized = true;
+        this.finalized = allFinalized;
     }
 
     protected isCSVScript(decompiled: (number | Uint8Array)[]): boolean {

package/test/add-refund-output.test.ts

@@ -52,6 +52,7 @@ describe('addRefundOutput ,  deterministic fee estimation', () => {
         feeRate?: number;
         feeUtxos?: UTXO[];
         autoAdjustAmount?: boolean;
+        debugFees?: boolean;
     }) {
         const utxo = createTaprootUtxo(taprootAddress, opts.utxoValue);
         return new FundingTransaction({
@@ -64,6 +65,7 @@ describe('addRefundOutput ,  deterministic fee estimation', () => {
             priorityFee: 0n,
             gasSatFee: 0n,
             mldsaSigner: null,
+            debugFees: !!opts.debugFees,
             ...(opts.feeUtxos !== undefined && { feeUtxos: opts.feeUtxos }),
             ...(opts.autoAdjustAmount !== undefined && { autoAdjustAmount: opts.autoAdjustAmount }),
         });
@@ -204,15 +206,38 @@ describe('addRefundOutput ,  deterministic fee estimation', () => {
         });
     });
 
+    // ================================================================
+    //  Fee underpayment guard: leftover absorbed into fee must still meet feeRate
+    // ================================================================
+    describe('fee underpayment guard', () => {
+        it('should throw when leftover would underpay feeRate (200 sats at feeRate=10)', async () => {
+            const utxoValue = 100_000n;
+            const amount = utxoValue - 200n;
+
+            const tx = buildFunding({ utxoValue, amount, feeRate: 10 });
+
+            await expect(tx.signTransaction()).rejects.toThrow(/Insufficient funds for fee/);
+        });
+
+        it('should throw when leftover is a token amount (1 sat) far below feeRate', async () => {
+            const utxoValue = 100_000n;
+            const amount = utxoValue - 1n;
+
+            const tx = buildFunding({ utxoValue, amount, feeRate: 5 });
+
+            await expect(tx.signTransaction()).rejects.toThrow(/Insufficient funds for fee/);
+        });
+    });
+
     // ================================================================
     //  Tolerance: sendBack < 0 but totalInput > amountSpent
     // ================================================================
-    describe('tolerance ,  effective fee is positive but less than estimated', () => {
-        it('should succeed when amount is close to totalInput leaving a small effective fee', async () => {
+    describe('tolerance ,  effective fee is positive but is a little bit less than estimated UTXO available', () => {
+        it('should succeed when amount+fees is close to totalInput', async () => {
             const utxoValue = 100_000n;
             // Leave 200 sats for fees ,  less than the estimated fee at high rate
             // but totalInput > amountSpent so it's valid
-            const amount = utxoValue - 200n;
+            const amount = utxoValue - 1109n;
 
             const tx = buildFunding({ utxoValue, amount, feeRate: 10 });
 
@@ -223,20 +248,80 @@ describe('addRefundOutput ,  deterministic fee estimation', () => {
 
             // Verify fee is exactly the 200 sats leftover
             const totalOut = signed.outs.reduce((sum, o) => sum + BigInt(o.value), 0n);
-            expect(utxoValue - totalOut).toBe(200n);
+            expect(utxoValue - totalOut).toBe(1109n);
+            expect(tx.transactionFee).toBe(1109n);
         });
 
-        it('should succeed with very small leftover (1 sat) as long as totalInput > amountSpent', async () => {
+        // Const real fees = 555n, dust = 330n
+        const shouldSucceed: [
+            delta: bigint,
+            succeed: boolean,
+            overflow: bigint,
+            message: string,
+        ][] = [
+            [0n, false, 0n, 'amount equal utxoValue'],
+            [1n, false, 0n, 'amount equal utxoValue less 1'],
+
+            // Check fees bondary
+            [553n, false, 0n, 'amount equal utxoValue less 553 (real fees - 2)'],
+            [554n, true, 0n, 'amount equal utxoValue less 554 (real fees - 1)'],
+            [555n, true, 0n, 'amount equal utxoValue less 555 (real fees)'],
+            [556n, true, 0n, 'amount equal utxoValue less 556 (real fees + 1)'],
+
+            // Check fees+dust bondaries
+            [555n + 329n, true, 0n, 'amount equal utxoValue less 884 (real fees + dust - 1)'],
+            [555n + 330n, true, 0n, 'amount equal utxoValue less 885 (real fees + dust)'],
+            [555n + 331n, true, 0n, 'amount equal utxoValue less 886 (real fees + dust + 1)'],
+
+            // If there is really a refund, a refund output section will be added
+            // to the tx, with a vbsize of 43 vbytes * 5 feeRate --> 215...
+            // Check the new fees+refund_section+dust boundaries
+            [
+                555n + 43n * 5n + 329n,
+                true,
+                0n,
+                'amount equal utxoValue less 1109 (real fees + refund + dust - 1)',
+            ],
+            [
+                555n + 43n * 5n + 330n,
+                true,
+                330n,
+                'amount equal utxoValue less 1110 (real fees + refund + dust)',
+            ],
+            [
+                555n + 43n * 5n + 331n,
+                true,
+                331n,
+                'amount equal utxoValue less 1111 (real fees + refund + dust + 1)',
+            ],
+        ];
+        it('should succeed with very small diff from calculated fees (1 sat)', async () => {
             const utxoValue = 100_000n;
-            const amount = utxoValue - 1n;
 
-            const tx = buildFunding({ utxoValue, amount, feeRate: 5 });
+            let tx: FundingTransaction | undefined = undefined;
+            for (const [delta, shouldSuccess, overflow, message] of shouldSucceed) {
+                let succeed = false;
+                try {
+                    const amount = utxoValue - delta;
 
-            const signed = await tx.signTransaction();
-            expect(signed.ins.length).toBeGreaterThan(0);
+                    tx = buildFunding({ utxoValue, amount, feeRate: 5, debugFees: false });
 
-            const totalOut = signed.outs.reduce((sum, o) => sum + BigInt(o.value), 0n);
-            expect(utxoValue - totalOut).toBe(1n);
+                    const signed = await tx.signTransaction();
+                    expect(signed.ins.length).toBeGreaterThan(0);
+
+                    const totalOut = signed.outs.reduce((sum, o) => sum + BigInt(o.value), 0n);
+
+                    //console.log('DELTA', utxoValue, totalOut, delta, overflow, tx.estimatedFees, tx.overflowFees,);
+                    expect(utxoValue - totalOut).toBe(delta - overflow);
+                    succeed = true;
+                } catch (e) {
+                    //console.log('E', e);
+                    succeed = false;
+                }
+
+                expect(succeed, message).toBe(shouldSuccess);
+                expect(tx?.overflowFees, message).toBe(overflow);
+            }
         });
     });