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

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();
+        });
+    });
+});

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

@@ -0,0 +1,202 @@
+/**
+ * csv-multisig-offline.test.ts
+ *
+ * Library-native multi-signer flow for spending CSV multisig UTXOs using
+ * OfflineTransactionManager — the documented offline signing API. No raw
+ * @btc-vision/bitcoin Psbt construction.
+ */
+
+import { beforeAll, describe, expect, it } from 'vitest';
+import {
+    crypto as bitCrypto,
+    networks,
+    payments,
+    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,
+    OfflineTransactionManager,
+    TransactionBuilder,
+} 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): UTXO {
+    return {
+        transactionId: '11'.repeat(32),
+        outputIndex: 0,
+        value,
+        scriptPubKey: {
+            hex: toHex(addr.scriptPubKey),
+            address: addr.address,
+        },
+        witnessScript: addr.tapscript,
+    };
+}
+
+describe('CSV multisig offline multi-signer flow', () => {
+    let signerA: UniversalSigner;
+    let signerB: UniversalSigner;
+    let signerC: UniversalSigner;
+
+    beforeAll(() => {
+        signerA = makeSigner('offline-A');
+        signerB = makeSigner('offline-B');
+        signerC = makeSigner('offline-C');
+    });
+
+    it('2-of-3 signers produce a broadcastable tx through OfflineTransactionManager', async () => {
+        const addr = buildAddr([signerA, signerB, signerC], 10, 2);
+        const utxo = makeUtxo(addr, 1_000_000n);
+        const recipient = payments.p2tr({
+            internalPubkey: toXOnly(signerA.publicKey) as XOnlyPublicKey,
+            network,
+        }).address as string;
+
+        // --- Coordinator (online): export funding state ---
+        const initialState = OfflineTransactionManager.exportFunding({
+            signer: signerA, // placeholder; real signer supplied per-hop
+            mldsaSigner: null,
+            network,
+            utxos: [utxo],
+            to: recipient,
+            amount: TransactionBuilder.MINIMUM_DUST,
+            feeRate: 1,
+            priorityFee: 0n,
+            gasSatFee: 0n,
+        });
+
+        // Before any signing, there's no partial PSBT yet.
+        expect(OfflineTransactionManager.csvMultisigGetStatus(initialState)).toEqual([]);
+
+        // --- Hop 1: signer A adds signature (offline env) ---
+        const hop1 = await OfflineTransactionManager.addCSVMultisigSignature(
+            initialState,
+            signerA,
+        );
+        expect(hop1.final).toBe(false);
+        expect(hop1.perInput).toHaveLength(1);
+        expect(hop1.perInput[0]!.required).toBe(2);
+        expect(hop1.perInput[0]!.collected).toBe(1);
+        expect(hop1.perInput[0]!.signers).toContain(toHex(toXOnly(signerA.publicKey)));
+
+        // --- Hop 2: signer B adds signature (different offline env) ---
+        const hop2 = await OfflineTransactionManager.addCSVMultisigSignature(
+            hop1.state,
+            signerB,
+        );
+        expect(hop2.final).toBe(true);
+        expect(hop2.perInput[0]!.collected).toBe(2);
+        expect(new Set(hop2.perInput[0]!.signers)).toEqual(
+            new Set([
+                toHex(toXOnly(signerA.publicKey)),
+                toHex(toXOnly(signerB.publicKey)),
+            ]),
+        );
+
+        // --- Finalize + extract (anyone, no key material required) ---
+        const rawTxHex = OfflineTransactionManager.csvMultisigFinalize(hop2.state);
+        expect(rawTxHex).toMatch(/^[0-9a-f]+$/);
+
+        // Sanity: the extracted tx has the expected witness shape and CSV sequence.
+        const state = OfflineTransactionManager.inspect(hop2.state);
+        expect(state.partialPsbtBase64).toBeDefined();
+    });
+
+    it('signer pubkey not in the tapscript is a no-op', async () => {
+        const addr = buildAddr([signerA, signerB], 5, 2);
+        const utxo = makeUtxo(addr, 500_000n);
+        const recipient = payments.p2tr({
+            internalPubkey: toXOnly(signerA.publicKey) as XOnlyPublicKey,
+            network,
+        }).address as string;
+
+        const initialState = OfflineTransactionManager.exportFunding({
+            signer: signerA,
+            mldsaSigner: null,
+            network,
+            utxos: [utxo],
+            to: recipient,
+            amount: TransactionBuilder.MINIMUM_DUST,
+            feeRate: 1,
+            priorityFee: 0n,
+            gasSatFee: 0n,
+        });
+
+        const hop1 = await OfflineTransactionManager.addCSVMultisigSignature(
+            initialState,
+            signerA,
+        );
+        expect(hop1.perInput[0]!.collected).toBe(1);
+
+        // signerC is not in this 2-of-2 tapscript.
+        const hop2 = await OfflineTransactionManager.addCSVMultisigSignature(
+            hop1.state,
+            signerC,
+        );
+        expect(hop2.perInput[0]!.collected).toBe(1);
+        expect(hop2.final).toBe(false);
+
+        // Finalize should throw because we're still below threshold.
+        expect(() => OfflineTransactionManager.csvMultisigFinalize(hop2.state)).toThrow(
+            /needs 2 signatures, got 1/,
+        );
+
+        // Now add the real second signer and finalize.
+        const hop3 = await OfflineTransactionManager.addCSVMultisigSignature(
+            hop2.state,
+            signerB,
+        );
+        expect(hop3.final).toBe(true);
+
+        const rawTxHex = OfflineTransactionManager.csvMultisigFinalize(hop3.state);
+        expect(rawTxHex).toMatch(/^[0-9a-f]+$/);
+    });
+
+    it('threshold = 1 finalizes in a single hop and emits a ready-to-broadcast tx', async () => {
+        const addr = buildAddr([signerA], 3, 1);
+        const utxo = makeUtxo(addr, 500_000n);
+        const recipient = payments.p2tr({
+            internalPubkey: toXOnly(signerA.publicKey) as XOnlyPublicKey,
+            network,
+        }).address as string;
+
+        const initialState = OfflineTransactionManager.exportFunding({
+            signer: signerA,
+            mldsaSigner: null,
+            network,
+            utxos: [utxo],
+            to: recipient,
+            amount: TransactionBuilder.MINIMUM_DUST,
+            feeRate: 1,
+            priorityFee: 0n,
+            gasSatFee: 0n,
+        });
+
+        const hop1 = await OfflineTransactionManager.addCSVMultisigSignature(
+            initialState,
+            signerA,
+        );
+        expect(hop1.final).toBe(true);
+
+        const rawTxHex = OfflineTransactionManager.csvMultisigFinalize(hop1.state);
+        expect(rawTxHex).toMatch(/^[0-9a-f]+$/);
+    });
+});

package/test/transaction-builders.test.ts

@@ -177,7 +177,7 @@ describe('Transaction Builders - End-to-End', () => {
             await expect(tx.signTransaction()).rejects.toThrow(/Insufficient funds/);
         });
 
-        it('should tolerate small fee estimation shortfalls when effective fee is still positive', async () => {
+        it('should tolerate small fee estimation shortfalls when amount + effective fee is near to input utxos', async () => {
             // When amount is close to totalInputAmount but leaves some sats for
             // fees, the estimated fee may exceed what's available. As long as the
             // effective fee (totalInputAmount - amountSpent) is positive, the
@@ -187,7 +187,7 @@ describe('Transaction Builders - End-to-End', () => {
 
             // Leave 200 sats for fees ,  less than the estimated ~77 sats/vB * ~77 vB
             // but still a positive effective fee
-            const amount = utxoValue - 200n;
+            const amount = utxoValue - 1110n;
 
             const tx = new FundingTransaction({
                 signer,
@@ -209,7 +209,31 @@ describe('Transaction Builders - End-to-End', () => {
 
             // Verify fee is exactly what was left over
             const totalOutputValue = signed.outs.reduce((sum, out) => sum + BigInt(out.value), 0n);
-            expect(utxoValue - totalOutputValue).toBe(200n);
+            expect(utxoValue - totalOutputValue).toBe(1110n);
+        });
+
+        it('should throw when leftover fee would underpay feeRate (no autoAdjust)', async () => {
+            // When amount is close to totalInputAmount but leaves less than the
+            // fee implied by feeRate, the transaction must NOT broadcast with an
+            // underpaid fee. Callers wanting send-max behavior must opt in via
+            // autoAdjustAmount=true.
+            const utxoValue = 100_000n;
+            const utxo = createTaprootUtxo(taprootAddress, utxoValue);
+            const amount = utxoValue - 200n;
+
+            const tx = new FundingTransaction({
+                signer,
+                network,
+                utxos: [utxo],
+                to: taprootAddress,
+                amount,
+                feeRate: 10,
+                priorityFee: 0n,
+                gasSatFee: 0n,
+                mldsaSigner: null,
+            });
+
+            await expect(tx.signTransaction()).rejects.toThrow(/Insufficient funds for fee/);
         });
 
         it('should auto-adjust amount when amount equals total UTXO value with autoAdjustAmount', async () => {
@@ -248,6 +272,48 @@ describe('Transaction Builders - End-to-End', () => {
             expect(fee).toBeLessThanOrEqual(expectedFee + 10n);
         });
 
+        it('should auto-adjust amount when amount + fees is higher than total UTXO value with autoAdjustAmount', async () => {
+            const amount = 100_000n;
+            const utxoValue = 100_100n; // Only 100 sats available for fees
+            const utxo = createTaprootUtxo(taprootAddress, utxoValue);
+            const feeRate = 2;
+
+            const tx = new FundingTransaction({
+                signer,
+                network,
+                utxos: [utxo],
+                to: taprootAddress,
+                amount: amount,
+                autoAdjustAmount: true,
+                feeRate,
+                priorityFee: 0n,
+                gasSatFee: 0n,
+                mldsaSigner: null,
+            });
+
+            const signed = await tx.signTransaction();
+
+            expect(signed.ins.length).toBeGreaterThan(0);
+            expect(signed.outs.length).toBeGreaterThan(0);
+            expect(signed.toHex()).toBeTruthy();
+
+            // Calculate total ouput for following tests
+            const totalOutputValue = signed.outs.reduce((sum, out) => sum + BigInt(out.value), 0n);
+
+            // The fee should be roughly feeRate * virtualSize
+            const fee = utxoValue - totalOutputValue;
+            const expectedFee = BigInt(Math.ceil(feeRate * signed.virtualSize()));
+            // Allow small variance due to fee estimation iterations
+            expect(fee).toBeGreaterThan(0n);
+            expect(fee).toBeGreaterThanOrEqual(expectedFee - 10n);
+            expect(fee).toBeLessThanOrEqual(expectedFee + 10n);
+
+            // The total output value should be less than utxoValue (fees deducted)
+            const expectedAmount = utxoValue - expectedFee;
+            expect(totalOutputValue).toBeLessThan(expectedAmount + 10n);
+            expect(totalOutputValue).toBeGreaterThan(expectedAmount - 10n);
+        });
+
         it('should not adjust amount when autoAdjustAmount is true but amount < totalInputAmount', async () => {
             const utxoValue = 100_000n;
             const sendAmount = 50_000n;