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

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@btc-vision/transaction",
     "type": "module",
-    "version": "1.8.7-beta.0",
+    "version": "1.8.8",
     "author": "BlobMaster41",
     "description": "OPNet transaction library allows you to create and sign transactions for the OPNet network.",
     "engines": {

package/src/epoch/validator/EpochValidator.ts

@@ -14,18 +14,37 @@ export class EpochValidator {
     }
 
     /**
-     * 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.
      */
     public static calculatePreimage(
         checksumRoot: Uint8Array,
         publicKey: Uint8Array,
         salt: Uint8Array,
+        useConcatenatedPreimage: boolean = false,
     ): Uint8Array {
         // 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] =
@@ -35,6 +54,30 @@ 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.
+     */
+    public static concatenatePreimage(
+        checksumRoot: Uint8Array,
+        publicKey: Uint8Array,
+        salt: Uint8Array,
+    ): Uint8Array {
+        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
      */
@@ -69,13 +112,18 @@ export class EpochValidator {
     /**
      * Verify an epoch solution using IPreimage
      */
-    public static verifySolution(challenge: IChallengeSolution, log: boolean = false): boolean {
+    public static verifySolution(
+        challenge: IChallengeSolution,
+        log: boolean = false,
+        useHashedPreimage: boolean = false,
+    ): boolean {
         try {
             const verification = challenge.verification;
             const calculatedPreimage = this.calculatePreimage(
                 verification.targetChecksum,
                 challenge.publicKey.toBuffer(),
                 challenge.salt,
+                useHashedPreimage,
             );
 
             const computedSolution = this.sha1(calculatedPreimage);
@@ -118,7 +166,10 @@ export class EpochValidator {
     /**
      * Validate epoch winner from raw data
      */
-    public static validateEpochWinner(epochData: RawChallenge): boolean {
+    public static validateEpochWinner(
+        epochData: RawChallenge,
+        useHashedPreimage: boolean = false,
+    ): boolean {
         try {
             const epochNumber = BigInt(epochData.epochNumber);
             const publicKey = Address.fromString(
@@ -143,6 +194,7 @@ export class EpochValidator {
                 verification.targetChecksum,
                 publicKey.toBuffer(),
                 salt,
+                useHashedPreimage,
             );
 
             const computedSolution = this.sha1(calculatedPreimage);
@@ -172,8 +224,11 @@ export class EpochValidator {
     /**
      * Validate epoch winner from Preimage instance
      */
-    public static validateChallengeSolution(challenge: IChallengeSolution): boolean {
-        return this.verifySolution(challenge);
+    public static validateChallengeSolution(
+        challenge: IChallengeSolution,
+        useHashedPreimage: boolean = false,
+    ): boolean {
+        return this.verifySolution(challenge, false, useHashedPreimage);
     }
 
     /**
@@ -187,8 +242,14 @@ export class EpochValidator {
         targetChecksum: Uint8Array,
         publicKey: Uint8Array,
         salt: Uint8Array,
+        useHashedPreimage: boolean = false,
     ): Uint8Array {
-        const preimage = this.calculatePreimage(targetChecksum, publicKey, salt);
+        const preimage = this.calculatePreimage(
+            targetChecksum,
+            publicKey,
+            salt,
+            useHashedPreimage,
+        );
         return this.sha1(preimage);
     }
 

package/src/transaction/TransactionFactory.ts

@@ -556,7 +556,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/src/transaction/builders/FundingTransaction.ts

@@ -31,9 +31,12 @@ export class FundingTransaction extends TransactionBuilder<TransactionType.FUNDI
 
         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;
@@ -59,27 +62,32 @@ export class FundingTransaction extends TransactionBuilder<TransactionType.FUNDI
                 }
             }
 
-            // 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
@@ -87,10 +95,7 @@ export class FundingTransaction extends TransactionBuilder<TransactionType.FUNDI
             this.splitInputs(this.amount);
         } else if (this.isPubKeyDestination) {
             const toHexClean = this.to.startsWith('0x') ? this.to.slice(2) : this.to;
-            const pubKeyScript: Script = script.compile([
-                fromHex(toHexClean),
-                opcodes.OP_CHECKSIG,
-            ]);
+            const pubKeyScript: Script = script.compile([fromHex(toHexClean), opcodes.OP_CHECKSIG]);
 
             this.addOutput({
                 value: toSatoshi(this.amount),

package/src/transaction/builders/TransactionBuilder.ts

@@ -46,6 +46,11 @@ export const MINIMUM_AMOUNT_REWARD: bigint = 330n; //540n;
 export const MINIMUM_AMOUNT_CA: bigint = 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
@@ -387,11 +392,28 @@ export abstract class TransactionBuilder<T extends TransactionType> extends Twea
      * @throws {Error} - If something went wrong
      */
     public async signPSBT(): Promise<Psbt> {
-        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;
     }
 
     /**
@@ -804,19 +826,33 @@ export abstract class TransactionBuilder<T extends TransactionType> extends Twea
                 );
             }
 
-            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.`,
+                    `Insufficient funds for fee: need at least ${-sendBackAmount} more sats to cover fees.`,
                 );
             }
         }
 
+        const amountNeeded = amountSpent + this.transactionFee;
+
+        const tolerance: bigint =
+            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/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 {