@btc-vision/transaction 1.8.6 → 1.8.7

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

@@ -4,6 +4,7 @@ import {
     address as bitAddress,
     applySignaturesToPsbt,
     crypto as bitCrypto,
+    equals,
     fromHex,
     getFinalScripts,
     isP2A,
@@ -45,6 +46,10 @@ import { UnisatSigner } from '../browser/extensions/UnisatSigner.js';
 import { canSignNonTaprootInput, isTaprootInput, pubkeyInScript, } from '../../signer/SignerUtils.js';
 import { witnessStackToScriptWitness } from '../utils/WitnessUtils.js';
 import { P2WDADetector } from '../../p2wda/P2WDADetector.js';
+import {
+    type CSVMultisigAddress,
+    CSVMultisigProvider,
+} from '../mineable/CSVMultisigProvider.js';
 import type { QuantumBIP32Interface } from '@btc-vision/bip32';
 import { MessageSigner } from '../../keypair/MessageSigner.js';
 import { type RotationSigner, type SignerMap } from '../../signer/AddressRotation.js';
@@ -154,6 +159,13 @@ export abstract class TweakedTransaction extends Logger implements Disposable {
     protected csvInputIndices: Set<number> = new Set();
     protected anchorInputIndices: Set<number> = new Set();
 
+    /**
+     * Track P2TR CSV multisig inputs together with the address descriptor needed
+     * to finalize them (tapscript + derived control block + parsed config).
+     * @protected
+     */
+    protected csvMultisigInputs: Map<number, CSVMultisigAddress> = new Map();
+
     protected regenerated: boolean = false;
     protected ignoreSignatureErrors: boolean = false;
     protected noSignatures: boolean = false;
@@ -391,6 +403,7 @@ export abstract class TweakedTransaction extends Logger implements Disposable {
         delete this.tweakedSigner;
         this.csvInputIndices.clear();
         this.anchorInputIndices.clear();
+        this.csvMultisigInputs.clear();
         this.inputSignerMap.clear();
         this.tweakedSignerCache.clear();
         delete this.parallelSigningConfig;
@@ -450,7 +463,8 @@ export abstract class TweakedTransaction extends Logger implements Disposable {
 
         for (const input of this.inputs) {
             // This would disable CSV! You need to check if the input has CSV
-            if (this.csvInputIndices.has(this.inputs.indexOf(input))) {
+            const idx = this.inputs.indexOf(input);
+            if (this.csvInputIndices.has(idx) || this.csvMultisigInputs.has(idx)) {
                 continue;
             }
 
@@ -755,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;
     }
 
     /**
@@ -1203,8 +1233,12 @@ export abstract class TweakedTransaction extends Logger implements Disposable {
                 if (inputSign) input.sighashType = inputSign;
             }
 
-            // Taproot internal key - use per-input signer in address rotation mode
-            if (this.addressRotationEnabled) {
+            // CSV multisig P2TR: script-path spend with NUMS internal key.
+            // Must come before the default key-path setup below.
+            if (this.processCSVMultisigP2TRInput(utxo, input, i, scriptPub)) {
+                // input fully configured for script-path spend
+            } else if (this.addressRotationEnabled) {
+                // Taproot internal key - use per-input signer in address rotation mode
                 input.tapInternalKey = this.internalPubKeyToXOnlyForInput(i);
             } else {
                 this.tweakSigner();
@@ -1254,8 +1288,10 @@ export abstract class TweakedTransaction extends Logger implements Disposable {
         }
 
         if (i === 0) {
-            // TapLeafScript if available
-            if (this.tapLeafScript) {
+            // TapLeafScript if available — but never clobber a CSV multisig input's
+            // own tapscript; its spend is a script-path that belongs to the UTXO,
+            // not to this transaction's contract leaf.
+            if (this.tapLeafScript && !this.csvMultisigInputs.has(i)) {
                 input.tapLeafScript = [this.tapLeafScript];
             }
 
@@ -1267,6 +1303,58 @@ export abstract class TweakedTransaction extends Logger implements Disposable {
         return input;
     }
 
+    /**
+     * Detect + configure a P2TR CSV multisig input for script-path spending.
+     *
+     * UTXOs of this shape carry the tapscript in `witnessScript`. The control
+     * block and internal pubkey are fully determined by the tapscript (single
+     * leaf tree, NUMS internal key) so the caller only needs to provide the
+     * tapscript.
+     *
+     * Returns true when the UTXO was recognized and the input was configured,
+     * false otherwise (caller falls back to the default P2TR key-path setup).
+     */
+    protected processCSVMultisigP2TRInput(
+        utxo: UTXO,
+        input: PsbtInputExtended,
+        i: number,
+        scriptPub: Uint8Array,
+    ): boolean {
+        if (!utxo.witnessScript) return false;
+
+        const tapscript =
+            utxo.witnessScript instanceof Uint8Array
+                ? utxo.witnessScript
+                : fromHex(utxo.witnessScript);
+
+        const addr = CSVMultisigProvider.deriveAddressFromTapscript(tapscript, this.network);
+        if (!addr) return false;
+
+        // Guard against spoofed witnessScripts on P2TR UTXOs from an unrelated
+        // address: the tapscript must hash back to this exact scriptPubKey.
+        if (!equals(addr.scriptPubKey, scriptPub)) {
+            return false;
+        }
+
+        (input as PsbtInputExtended & { tapLeafScript: TapLeafScript[] }).tapLeafScript = [
+            {
+                leafVersion: addr.leafVersion,
+                script: addr.tapscript,
+                controlBlock: addr.controlBlock,
+            },
+        ];
+        input.tapInternalKey = addr.internalPubkey as XOnlyPublicKey;
+
+        // Force a CSV-compatible nSequence so OP_CHECKSEQUENCEVERIFY passes.
+        (input as { sequence: number }).sequence = this.setCSVSequence(
+            addr.config.csvBlocks,
+            this.sequence,
+        );
+
+        this.csvMultisigInputs.set(i, addr);
+        return true;
+    }
+
     protected processP2WSHInput(utxo: UTXO, input: PsbtInputExtended, i: number): void {
         // P2WSH requires a witnessScript
         if (!utxo.witnessScript) {
@@ -1350,6 +1438,19 @@ export abstract class TweakedTransaction extends Logger implements Disposable {
             };
         }
 
+        const csvMultisigAddr = this.csvMultisigInputs.get(inputIndex);
+        if (csvMultisigAddr) {
+            const tapSigs = input.tapScriptSig ?? [];
+            const witnessStack = CSVMultisigProvider.buildFinalWitnessFromTapScriptSigs(
+                tapSigs,
+                csvMultisigAddr,
+            );
+            return {
+                finalScriptSig: undefined,
+                finalScriptWitness: witnessStackToScriptWitness(witnessStack),
+            };
+        }
+
         if (isP2WSH && isSegwit && input.witnessScript) {
             if (!input.partialSig || input.partialSig.length === 0) {
                 throw new Error(`No signatures for P2WSH input #${inputIndex}`);
@@ -1424,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);
+            }
         });
     });
 

package/test/csv-multisig-offline-edges.test.ts

@@ -0,0 +1,293 @@
+/**
+ * csv-multisig-offline-edges.test.ts
+ *
+ * Edge cases for the OfflineTransactionManager CSV multisig API:
+ *   - csvMultisigGetStatus standalone
+ *   - csvMultisigFinalize error paths
+ *   - addCSVMultisigSignature idempotency + non-cosigner no-op on first hop
+ *   - Serializer v2 round-trip of partialPsbtBase64
+ *   - signPSBT returns a partial PSBT for under-threshold CSV inputs
+ */
+
+import { beforeAll, describe, expect, it } from 'vitest';
+import {
+    crypto as bitCrypto,
+    networks,
+    payments,
+    Psbt,
+    toHex,
+    toXOnly,
+    type XOnlyPublicKey,
+} from '@btc-vision/bitcoin';
+import { type UniversalSigner } from '@btc-vision/ecpair';
+import type { UTXO } from '../build/opnet.js';
+import {
+    CSVMultisigProvider,
+    EcKeyPair,
+    FundingTransaction,
+    OfflineTransactionManager,
+    TransactionBuilder,
+    TransactionSerializer,
+} from '../build/opnet.js';
+
+const network = networks.regtest;
+
+function makeSigner(seed: string): UniversalSigner {
+    return EcKeyPair.fromPrivateKey(
+        bitCrypto.sha256(new TextEncoder().encode(seed)),
+        network,
+    );
+}
+
+function buildAddr(signers: UniversalSigner[], csvBlocks: number, threshold: number) {
+    const pubkeys = signers.map((s) => toXOnly(s.publicKey) as XOnlyPublicKey);
+    return CSVMultisigProvider.generateAddress({ pubkeys, threshold, csvBlocks }, network);
+}
+
+function makeUtxo(
+    addr: ReturnType<typeof buildAddr>,
+    value: bigint,
+    txid: string = '22'.repeat(32),
+): UTXO {
+    return {
+        transactionId: txid,
+        outputIndex: 0,
+        value,
+        scriptPubKey: {
+            hex: toHex(addr.scriptPubKey),
+            address: addr.address,
+        },
+        witnessScript: addr.tapscript,
+    };
+}
+
+function fundingState(
+    addr: ReturnType<typeof buildAddr>,
+    utxo: UTXO,
+    placeholderSigner: UniversalSigner,
+): string {
+    const recipient = payments.p2tr({
+        internalPubkey: toXOnly(placeholderSigner.publicKey) as XOnlyPublicKey,
+        network,
+    }).address as string;
+
+    return OfflineTransactionManager.exportFunding({
+        signer: placeholderSigner,
+        mldsaSigner: null,
+        network,
+        utxos: [utxo],
+        to: recipient,
+        amount: TransactionBuilder.MINIMUM_DUST,
+        feeRate: 1,
+        priorityFee: 0n,
+        gasSatFee: 0n,
+    });
+}
+
+describe('OfflineTransactionManager CSV multisig — edges', () => {
+    let signerA: UniversalSigner;
+    let signerB: UniversalSigner;
+    let signerC: UniversalSigner;
+    let signerD: UniversalSigner; // never a cosigner anywhere
+
+    beforeAll(() => {
+        signerA = makeSigner('edges-A');
+        signerB = makeSigner('edges-B');
+        signerC = makeSigner('edges-C');
+        signerD = makeSigner('edges-D');
+    });
+
+    // ----------------------------------------------------------------
+    // csvMultisigGetStatus
+    // ----------------------------------------------------------------
+    describe('csvMultisigGetStatus', () => {
+        it('returns [] when no partial PSBT has been produced yet', () => {
+            const addr = buildAddr([signerA, signerB], 5, 2);
+            const utxo = makeUtxo(addr, 200_000n);
+            const state = fundingState(addr, utxo, signerA);
+
+            expect(OfflineTransactionManager.csvMultisigGetStatus(state)).toEqual([]);
+        });
+
+        it('reflects the same status as the hop result after addCSVMultisigSignature', async () => {
+            const addr = buildAddr([signerA, signerB, signerC], 5, 2);
+            const utxo = makeUtxo(addr, 200_000n);
+            const state = fundingState(addr, utxo, signerA);
+
+            const hop1 = await OfflineTransactionManager.addCSVMultisigSignature(state, signerA);
+            const direct = OfflineTransactionManager.csvMultisigGetStatus(hop1.state);
+
+            expect(direct).toEqual(hop1.perInput);
+            expect(direct[0]!.collected).toBe(1);
+            expect(direct[0]!.required).toBe(2);
+        });
+
+        it('reports collected === threshold for finalized inputs (threshold=1 single hop)', async () => {
+            const addr = buildAddr([signerA], 3, 1);
+            const utxo = makeUtxo(addr, 200_000n);
+            const state = fundingState(addr, utxo, signerA);
+
+            const hop1 = await OfflineTransactionManager.addCSVMultisigSignature(state, signerA);
+
+            const status = OfflineTransactionManager.csvMultisigGetStatus(hop1.state);
+            expect(status).toHaveLength(1);
+            expect(status[0]!.required).toBe(1);
+            expect(status[0]!.collected).toBe(1);
+        });
+    });
+
+    // ----------------------------------------------------------------
+    // csvMultisigFinalize error paths
+    // ----------------------------------------------------------------
+    describe('csvMultisigFinalize', () => {
+        it('throws when no partial PSBT exists in state', () => {
+            const addr = buildAddr([signerA, signerB], 5, 2);
+            const utxo = makeUtxo(addr, 200_000n);
+            const state = fundingState(addr, utxo, signerA);
+
+            expect(() => OfflineTransactionManager.csvMultisigFinalize(state)).toThrow(
+                /No partial PSBT/i,
+            );
+        });
+
+        it('throws when the partial PSBT is below threshold', async () => {
+            const addr = buildAddr([signerA, signerB, signerC], 5, 2);
+            const utxo = makeUtxo(addr, 200_000n);
+            const state = fundingState(addr, utxo, signerA);
+
+            const hop1 = await OfflineTransactionManager.addCSVMultisigSignature(state, signerA);
+            expect(hop1.final).toBe(false);
+
+            expect(() => OfflineTransactionManager.csvMultisigFinalize(hop1.state)).toThrow(
+                /needs 2 signatures, got 1/,
+            );
+        });
+    });
+
+    // ----------------------------------------------------------------
+    // addCSVMultisigSignature edge cases
+    // ----------------------------------------------------------------
+    describe('addCSVMultisigSignature', () => {
+        it('is idempotent — re-signing with the same cosigner does not double-count', async () => {
+            const addr = buildAddr([signerA, signerB, signerC], 5, 2);
+            const utxo = makeUtxo(addr, 200_000n);
+            const state = fundingState(addr, utxo, signerA);
+
+            const hop1 = await OfflineTransactionManager.addCSVMultisigSignature(state, signerA);
+            expect(hop1.perInput[0]!.collected).toBe(1);
+
+            const hop2 = await OfflineTransactionManager.addCSVMultisigSignature(
+                hop1.state,
+                signerA,
+            );
+            expect(hop2.perInput[0]!.collected).toBe(1);
+            expect(hop2.final).toBe(false);
+        });
+
+        it('non-cosigner on a non-first hop leaves the partial PSBT unchanged', async () => {
+            const addr = buildAddr([signerA, signerB], 5, 2);
+            const utxo = makeUtxo(addr, 200_000n);
+            const state = fundingState(addr, utxo, signerA);
+
+            const hop1 = await OfflineTransactionManager.addCSVMultisigSignature(state, signerA);
+            expect(hop1.perInput[0]!.collected).toBe(1);
+
+            // signerD is in neither the tapscript nor the original signer slot
+            const hop2 = await OfflineTransactionManager.addCSVMultisigSignature(
+                hop1.state,
+                signerD,
+            );
+            expect(hop2.perInput[0]!.collected).toBe(1);
+            expect(hop2.final).toBe(false);
+        });
+
+        it('reaches threshold across three distinct cosigners (2-of-3 with C+B)', async () => {
+            const addr = buildAddr([signerA, signerB, signerC], 5, 2);
+            const utxo = makeUtxo(addr, 200_000n);
+            // Placeholder signer is A — but the actual cosigners are C then B.
+            const state = fundingState(addr, utxo, signerA);
+
+            // Build PSBT using A as the placeholder for the first hop;
+            // immediately overlay C's signature in a second hop.
+            const hopA = await OfflineTransactionManager.addCSVMultisigSignature(state, signerA);
+            expect(hopA.perInput[0]!.collected).toBe(1);
+
+            const hopC = await OfflineTransactionManager.addCSVMultisigSignature(
+                hopA.state,
+                signerC,
+            );
+            expect(hopC.perInput[0]!.collected).toBe(2);
+            expect(hopC.final).toBe(true);
+
+            // Finalization succeeds even though signerB never participated.
+            const rawTxHex = OfflineTransactionManager.csvMultisigFinalize(hopC.state);
+            expect(rawTxHex).toMatch(/^[0-9a-f]+$/);
+        });
+    });
+
+    // ----------------------------------------------------------------
+    // Serializer v2 round-trip
+    // ----------------------------------------------------------------
+    describe('serializer v2 — partialPsbtBase64 round-trip', () => {
+        it('omits the field on a freshly exported state', () => {
+            const addr = buildAddr([signerA, signerB], 5, 2);
+            const utxo = makeUtxo(addr, 200_000n);
+            const state = fundingState(addr, utxo, signerA);
+
+            const decoded = TransactionSerializer.fromBase64(state);
+            expect(decoded.partialPsbtBase64).toBeUndefined();
+        });
+
+        it('round-trips the partial PSBT verbatim after a signing hop', async () => {
+            const addr = buildAddr([signerA, signerB], 5, 2);
+            const utxo = makeUtxo(addr, 200_000n);
+            const state = fundingState(addr, utxo, signerA);
+
+            const hop1 = await OfflineTransactionManager.addCSVMultisigSignature(state, signerA);
+
+            const decoded = TransactionSerializer.fromBase64(hop1.state);
+            expect(decoded.partialPsbtBase64).toBeDefined();
+
+            // Sanity: the carried PSBT actually parses and has one tapScriptSig.
+            const psbt = Psbt.fromBase64(decoded.partialPsbtBase64!, { network });
+            expect(psbt.data.inputs[0]!.tapScriptSig).toHaveLength(1);
+
+            // Round-trip via toBase64 yields a byte-identical payload.
+            const reEncoded = TransactionSerializer.toBase64(decoded);
+            expect(reEncoded).toBe(hop1.state);
+        });
+    });
+
+    // ----------------------------------------------------------------
+    // signPSBT semantic shift: returns the (possibly partial) PSBT
+    // ----------------------------------------------------------------
+    describe('TransactionBuilder.signPSBT — partial PSBT semantics', () => {
+        it('returns a PSBT with the tapScriptSig but no finalScriptWitness for under-threshold CSV input', async () => {
+            const addr = buildAddr([signerA, signerB, signerC], 5, 2);
+            const utxo = makeUtxo(addr, 200_000n);
+            const recipient = payments.p2tr({
+                internalPubkey: toXOnly(signerA.publicKey) as XOnlyPublicKey,
+                network,
+            }).address as string;
+
+            const tx = new FundingTransaction({
+                signer: signerA,
+                mldsaSigner: null,
+                network,
+                utxos: [utxo],
+                to: recipient,
+                amount: TransactionBuilder.MINIMUM_DUST,
+                feeRate: 1,
+                priorityFee: 0n,
+                gasSatFee: 0n,
+            });
+
+            const psbt = await tx.signPSBT();
+            const input = psbt.data.inputs[0]!;
+
+            expect(input.tapScriptSig).toBeDefined();
+            expect(input.tapScriptSig).toHaveLength(1);
+            expect(input.finalScriptWitness).toBeUndefined();
+        });
+    });
+});